NavList

Example

Props

Aria current

Use aria-current to indicate which NavItem represents the current item. Typically “page” will be the appropriate value.

<NavItem href="/path" aria-current="page">
  Current page
</NavItem>

Only one item per list may be current at any given time.

Href

Each navigation item requires an href prop.

<NavItem href="/path">Item label</NavItem>

Items links should always open in the current window. Avoid using navigation items for links to other applications or outside resources.

Patterns

Icons

Use icons only when they add essential value and have a strong association with the text. Never use icons for decoration.

When providing an icon, wrap the item label with Text so it inherits the correct layout and appearance.

Do not alternate betwen icon and text-only navigation items within the same context. Grouped items should either all have icons or all be text-only.

Dividers

Dividers can be used to separate navigation items. Prefer navigation groups for grouping related items under a title.

Choose either dividers or groups to separate items, using both is redundant. Avoid using dividers inside of a navigation group.

Groups

Group related navigation items together into categories using the NavGroup component.

If some navigation items don’t naturally fall into a category, place them at the top. Grouped items should either all have icons or all be text-only.

Accessibility

List label

The NavList should be labelled for users of assistive technology, offering any relevant context for the items contained within.

Reference an element by ID with aria-labelledby, or label the nav list directly using aria-label.

<Heading id="list-heading">
  List heading
</Heading>
<NavList aria-labelledby="list-heading">
  ...
</NavList>

// ---------- OR ----------

<NavList aria-label="List heading">
  ...
</NavList>

Best practices

Labelling

Use sentence case and be descriptive. Choose labels for navigation items that clearly communicate where they will go. Likewise, choose group titles that clearly communicate the shared theme among the contained items.

Reduce unnecessary words to ensure simplicity. While descriptive, navigation items and group titles should be succinct.

Text overflow

When the item text is too long for the horizontal space available, it wraps to form another line.

Item labels should never be so long that they require truncation, except in instances where navigation is user-generated.