Navigation Rail

Navigation rails provide persistent vertical navigation for tablet and desktop layouts, supporting 3–7 primary destinations with optional header content and a floating action button. Not intended for mobile phone layouts — use ds-navigation-bar at narrow viewports instead.

Basic Usage

A rail with three destinations. One destination is active. The rail sits along the side of the viewport, keeping navigation visible without consuming the full width of a drawer.

Home Search Favorites 
<ds-navigation-rail>
  <ds-navigation-rail-item icon="home" value="home" active>Home</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="search" value="search">Search</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="favorite" value="favorites">Favorites</ds-navigation-rail-item>
</ds-navigation-rail>

With Badges

Destinations can show badge counts for notifications.

Home Alerts Messages Profile 
<ds-navigation-rail>
  <ds-navigation-rail-item icon="home" value="home" active>Home</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="notifications" value="notifications" badge="5">Alerts</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="chat" value="messages" badge="12">Messages</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="person" value="profile">Profile</ds-navigation-rail-item>
</ds-navigation-rail>

Header and FAB

Use the header and fab slots for branded content and a primary action.

Home Calendar Work Profile 
<ds-navigation-rail>
  <div slot="header">NR</div>
  <ds-navigation-rail-item icon="home" value="home" active>Home</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="event" value="calendar">Calendar</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="work" value="work">Work</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="person" value="profile">Profile</ds-navigation-rail-item>
  <ds-fab slot="fab" icon="add"></ds-fab>
</ds-navigation-rail>

States

Items can be active or disabled.

Home Favorites Profile 
<ds-navigation-rail>
  <ds-navigation-rail-item icon="home" value="home" active>Home</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="favorite" value="favorites">Favorites</ds-navigation-rail-item>
  <ds-navigation-rail-item icon="person" value="profile" disabled>Profile</ds-navigation-rail-item>
</ds-navigation-rail>

Interactive Demo

Click destinations to see the selection event.

Home Search Favorites Profile

Usage Guidelines

  • When to use: Tablet and desktop layouts with 3–7 primary destinations of similar importance, where a full navigation drawer would be too heavy but a bottom bar too small.
  • When not to use: Avoid on mobile phone viewports — use ds-navigation-bar instead. Avoid when destinations are fewer than three or more than seven.
  • Composition: Always keep exactly one destination active. Use the header slot for branding or a menu toggle. Use the FAB slot for a primary action that remains accessible at all times.
  • Common mistakes: Using icon-only items without visible labelling — show labels on the active item at minimum. Exceeding seven destinations makes the rail feel crowded.

API

DSNavigationRail

Container component for rail destinations.

Slots

Slot Description
header Content above destinations (logo or menu trigger)
fab Floating action button below destinations
(default) Destination items (ds-navigation-rail-item)

Events

Event Detail Description
ds-navigation-rail:select { value: string, label: string } Fired when a destination is selected

CSS Parts

Part Description
container The navigation rail container
destinations Wrapper for destination items

DSNavigationRailItem

Individual navigation destination item.

Attributes

Attribute Type Default Description
value string - Value for this destination
icon string - Material Symbol icon name
label string - Destination label (or use slot content)
active boolean false Marks the destination as active
disabled boolean false Disables the destination
badge string - Badge content (number or text)

Events

Event Detail Description
ds-navigation-rail-item:click { value: string, label: string } Fired when item is clicked (not disabled)

CSS Parts

Part Description
container The item container button
icon The icon element
label The label text
indicator The active indicator
badge The badge element

CSS Custom Properties

Property Default Description
--ds-navigation-rail-hover-color --md-sys-color-on-surface Hover state layer background color
--ds-navigation-rail-hover-opacity 0.08 Hover state layer opacity
--ds-navigation-rail-pressed-opacity 0.12 Pressed/active state layer opacity
--ds-navigation-rail-active-bg --md-sys-color-secondary-container Active indicator background color

MD3 Specification

Navigation Rail — Material Design 3

Browser Support

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Accessibility

Keyboard Interaction

Key Context Expected Result
Tab Outside the rail Moves focus into the rail, onto the active destination (the first enabled one if none is active). The rail is a single tab stop.
Tab / Shift+Tab Inside the rail Moves focus out of the rail. Tabbing back in returns to the active destination.
ArrowDown / ArrowUp Inside the rail Moves focus to the next / previous enabled destination, wrapping at the ends. Does not select.
Home / End Inside the rail Moves focus to the first / last enabled destination
Enter / Space Focus on a destination Selects the destination and fires the select event. Focus stays on it.

Semantics

  • The rail uses role="navigation"; each item uses role="tab".
  • Arrow keys move focus without selecting (manual activation), so moving between destinations doesn't navigate away on every key press. Selection happens on Enter, Space or a click.
  • Active items expose aria-selected="true"; disabled items expose aria-disabled="true".
  • Destination labels are visible on the active item; all items carry a descriptive aria-label.