NavigationRail

The NavigationRail component provides a persistent and convenient way to navigate between primary destinations in an application. It is designed to present the top-level navigation in a vertical orientation that is always visible on the left side of the screen.

Use cases

Make sure the NavigationRail is suitable for your use case. There may be other, more appropriate components available.

Use case	NavigationRail	AppBar	BottomNavigation	Pagination	List
Persistent, application-wide navigation and functionality	✅	❌	❌	❌	❌
Information and actions about the current screen only	❌	✅	❌	❌	❌
Navigating between primary application views	❌	❌	✅	❌	❌
Navigating queried data, such as the results of a search	❌	❌	❌	✅	❌
Grouping generic items of content and making them enumerable	❌	❌	❌	❌	✅

Structure

NavigationRail is divided into three main sections:

• NavigationRail.Header
• NavigationRail.Content
• NavigationRail.Footer

These are used to create the following basic structure. Note that NavigationRail.Footer is nested inside NavigationRail.Content.

<NavigationRail.Root>
  <NavigationRail.Header>...</NavigationRail.Header>
  <NavigationRail.Content>
    ...
    <NavigationRail.Footer>...</NavigationRail.Footer>
  </NavigationRail.Content>
</NavigationRail.Root>

NavigationRail.Header

This is for the application branding and NavigationRail.ToggleButton, for expanding the rail and revealing full text labels for the navigation options.

<NavigationRail.Header>
  <Icon alt="Acme app" href={`${svgBentley}#icon-large`} size="large" />
  <NavigationRail.ToggleButton />
</NavigationRail.Header>

NavigationRail.Content

The NavigationRail.Content component houses a number of interactive navigation components. These can each be one of NavigationRail.Anchor or NavigationRail.Button.

You can group related navigation components using the NavigationRail.List and NavigationRail.ListItem components. Place a Divider between groups for clear visual demarcation.

<NavigationRail.Content>
  <NavigationRail.List>
    <NavigationRail.ListItem>...</NavigationRail.ListItem>
    <NavigationRail.ListItem>...</NavigationRail.ListItem>
    <NavigationRail.ListItem>...</NavigationRail.ListItem>
  </NavigationRail.List>
  <Divider role="presentation" />
  <NavigationRail.List>
    <NavigationRail.ListItem>...</NavigationRail.ListItem>
    <NavigationRail.ListItem>...</NavigationRail.ListItem>
  </NavigationRail.List>
  <Divider role="presentation" />
  <NavigationRail.Anchor>...</NavigationRail.Anchor>

  <NavigationRail.Footer>...</NavigationRail.Footer>
</NavigationRail.Content>

Note the standalone NavigationRail.Anchor. Not all items belong to groups.

Presentational dividers

Note that the Divider takes role="presentation". The closing of one list and the opening of the next is already determinable. An explicit role="separator" element is not needed.

See the presentational dividers section in the Divider guide.

NavigationRail.Footer

Any supplementary items, such as settings or account preferences, should be placed in the Footer. The same grouping rules apply.

<NavigationRail.Footer>
  <NavigationRail.List>
    <NavigationRail.ListItem>
      <NavigationRail.Button icon={`${svgSettings}#icon-large`} label="Settings" />
    </NavigationRail.ListItem>
    <NavigationRail.ListItem>
      <NavigationRail.Anchor icon={`${svgAccount}#icon-large`} label="Account" />
    </NavigationRail.ListItem>
  </NavigationRail.List>
</NavigationRail.Footer>

Interaction

Choose a NavigationRail.Anchor or NavigationRail.Button, depending on the type of interaction.

Component	Interaction
NavigationRail.Anchor	Navigation between screens
NavigationRail.Button	Action on the current screen (e.g. opening a dialog)

NavigationRail.ListItem is not itself interactive. It houses either a NavigationRail.Anchor or a NavigationRail.Button.

The active prop

Mark a NavigationRail.Anchor’s current link destination with the active prop. This prop is not supported on NavigationRail.Button.

Routing

Each NavigationRail.Anchor must take the user to a separate screen belonging to the application. Each screen/page must have a unique title. If you are using a single-page application architecture, the <title> will have to be updated dynamically. When the new screen is rendered, keyboard focus must be relocated. Typically, this will be to the <h1> heading of the new screen, giving context to screen reader users.

Your router component may implement some of these behaviors for you.

The suffix prop

Use the suffix prop to display additional information. For example, for items that open in a new tab, render an icon with the alternate text “(opens in a new tab)”.

<NavigationRail.Anchor suffix="(opens in a new tab)">Help</NavigationRail.Anchor>

Examples

Comprehensive

Combine NavigationRail with other components to create a more complex navigation experience.

In the example below:

• The NavigationRail.Root state is controlled via the expanded and setExpanded props, enabling conditional rendering based on whether the rail is expanded or collapsed.
• The Badge component is used to display a notification indicator for the “Notifications” item.
  • When the rail is collapsed, a dot badge is shown next to the icon. The suffix prop is used to display the notification count via the tooltip, so that the resulting tooltip reads “Notifications (3)”.
  • When the rail is expanded, an inline badge with the notification count “3” is displayed next to the label via the suffix prop.
  • In both states, the suffix prop contributes to the accessible name by adding a “(3 unread)” message, resulting in the accessible name “Notifications (3 unread)”.
• The Menu component is used to expose multiple related actions for the “Account” item.

✅ Do

• Include a NavigationRail.Header, NavigationRail.Content, and NavigationRail.Footer, in that order.
• Organize related items into NavigationRail.Lists separated by presentational Dividers.
• Use the NavigationRail.Anchor and NavigationRail.Button components for navigational items.
• Use NavigationRail.Button for any items that do not navigate the user away from the current screen.

🚫 Don’t

• Don’t insert Dividers between NavigationRail.ListItems.
• Don’t place important navigation items in NavigationRail.Footer.
• Don’t make multiple NavigationRail.Anchors active at the same time.