Skip to content
StrataKit Docs

unstable_NavigationRail API

Component status:
unstable

Import

Section titled “Import”
import { unstable_NavigationRail as NavigationRail } from "@stratakit/structures";
// OR
import * as NavigationRail from "@stratakit/structures/unstable_NavigationRail";
Section titled “NavigationRail.Root”
Base element: <nav>

The NavigationRail presents top-level navigation items in a vertical orientation.

Example:

<NavigationRail.Root>
  <NavigationRail.Header>
    <IconButton label="Home" icon={applicationIcon} href="/" />
    <NavigationRail.ToggleButton />
  </NavigationRail.Header>


  <NavigationRail.Content>
    <NavigationRail.List>
      <NavigationRail.ListItem>
        <NavigationRail.Anchor label="Dashboard" icon={dashboardIcon} href="/dashboard" />
      </NavigationRail.ListItem>
      <NavigationRail.ListItem>
        <NavigationRail.Anchor label="Projects" icon={projectsIcon} href="/projects" />
      </NavigationRail.ListItem>
      <NavigationRail.ListItem>
        <NavigationRail.Anchor label="Reports" icon={reportsIcon} href="/reports" />
      </NavigationRail.ListItem>
    </NavigationRail.List>


    <NavigationRail.Footer>
      <NavigationRail.List>
        <NavigationRail.ListItem>
          <NavigationRail.Button label="Help" icon={helpIcon} onClick={…} />
        </NavigationRail.ListItem>
        <NavigationRail.ListItem>
          <NavigationRail.Button label="Settings" icon={settingsIcon} onClick={…} />
        </NavigationRail.ListItem>
        <NavigationRail.ListItem>
          <NavigationRail.Button label="Profile" icon={userIcon} onClick={…} />
        </NavigationRail.ListItem>
      </NavigationRail.List>
   </NavigationRail.Footer>
  </NavigationRail.Content>
</NavigationRail.Root>
Section titled “defaultExpanded”
Type: boolean | undefined (optional)
Default: false

The initial expanded state of the NavigationRail when it is first rendered.

This prop is recommended over expanded when you don’t need to fully control the expanded state from the outside.

This prop will be ignored if the expanded prop is provided.

Section titled “expanded”
Type: boolean | undefined (optional)

Control whether the NavigationRail is expanded or collapsed.

When true, the NavigationRail shows both icons and labels for its items. When false, it shows only icons, with labels available as tooltips.

This prop is optional; if not provided, the NavigationRail will manage its own state internally.

This should be used in conjunction with the setExpanded prop to reflect internal state changes.

Section titled “render”
Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

Section titled “setExpanded”
Type: ((expanded: boolean) => void) | undefined (optional)

Callback that is called when the expanded state of the NavigationRail changes.

This is useful for syncing the internal state of the NavigationRail with external state.

Section titled “NavigationRail.Header”
Base element: <nav>

NavigationRail.Header represents the header (i.e. top) section of the NavigationRail and is visually aligned with the page header next to it.

Can contain a logo and a NavigationRail.ToggleButton to collapse/expand the NavigationRail.

Note: This component is expected to hug the top edge of the page.

Section titled “Additional props”
Section titled “NavigationRail.ToggleButton”
Base element: <button>

NavigationRail.ToggleButton toggles the expanded/collapsed state of the NavigationRail. It is typically placed inside NavigationRail.Header, next to the logo.

When this button is clicked, it toggles the internal expanded state of the NavigationRail, and also calls the setExpanded callback prop if provided, to allow syncing with external state.

Section titled “label”
Type: string | undefined (optional)
Default: "Expand navigation".

Customize the accessible label of the toggle button.

Section titled “Additional props”
Section titled “NavigationRail.Content”
Base element: <div>

NavigationRail.Content is a wraps the main content of the NavigationRail, including the primary navigation list and an optional footer.

Example:

<NavigationRail.Content>
  <NavigationRail.List>…</NavigationRail.List>


  <NavigationRail.Footer>
    <NavigationRail.List>…</NavigationRail.List>
  </NavigationRail.Footer>
</NavigationRail.Content>
Section titled “Additional props”
Section titled “NavigationRail.List”
Base element: <div>

The NavigationRail.List represents a list of top-level navigation items.

It should be used within NavigationRail.Content and should contain NavigationRail.ListItem elements, which in turn can contain NavigationRail.Anchor or NavigationRail.Button.

Example (with NavigationRail.Anchor):

<NavigationRail.List>
  <NavigationRail.ListItem>
    <NavigationRail.Anchor label="Home" icon={homeIcon} href="/" />
  </NavigationRail.ListItem>
  <NavigationRail.ListItem>
    <NavigationRail.Anchor label="Projects" icon={projectsIcon} href="/projects" />
  </NavigationRail.ListItem>
</NavigationRail.List>

Example (with NavigationRail.Button):

<NavigationRail.List>
  <NavigationRail.ListItem>
    <NavigationRail.Button label="Help" icon={helpIcon} onClick={…} />
  </NavigationRail.ListItem>
  <NavigationRail.ListItem>
    <NavigationRail.Button label="Settings" icon={settingsIcon} onClick={…}  />
  </NavigationRail.ListItem>
</NavigationRail.List>

Multiple NavigationRail.List elements can be used together and be separated by a Divider.

Section titled “Additional props”
Section titled “NavigationRail.ListItem”
Base element: <div>

The NavigationRail.Item represents a single navigation list item, which should contain either a NavigationRail.Anchor or a NavigationRail.Button.

Example:

<NavigationRail.ListItem>
  <NavigationRail.Anchor label="Home" icon={homeIcon} href="/" />
</NavigationRail.ListItem>
// or
<NavigationRail.ListItem>
  <NavigationRail.Button label="Settings" icon={settingsIcon} onClick={…} />
</NavigationRail.ListItem>

Note: This is a non-interactive wrapper element and should not directly handle user interactions.

Section titled “Additional props”
Section titled “NavigationRail.Button”
Base element: <button>

NavigationRail.Button is used for actions that do not navigate to a new page, but rather perform an in-page action, such as opening a dialog or menu.

Should be used inside NavigationRail.ListItem and must have a short label and a recognizable icon. The label will be shown as a tooltip when the NavigationRail is collapsed.

Example:

<NavigationRail.ListItem>
  <NavigationRail.Button label="Notifications" icon={notificationsIcon} onClick={showNotificationsDialog} />
</NavigationRail.ListItem>
Section titled “icon”
Type: string | Element (required)
Section titled “label”
Type: string (required)
Section titled “Additional props”
Section titled “NavigationRail.Anchor”
Base element: <a>

NavigationRail.Anchor is used for top-level navigation items that link to major pages.

Should be used inside NavigationRail.ListItem and must have a short label and a recognizable icon. The label will be shown as a tooltip when the NavigationRail is collapsed.

Example:

<NavigationRail.ListItem>
  <NavigationRail.Anchor label="Home" icon={homeIcon} href="/" />
</NavigationRail.ListItem>
Section titled “icon”
Type: string | Element (required)
Section titled “label”
Type: string (required)
Section titled “active”
Type: boolean | undefined (optional)

Whether the anchor is currently active (i.e. represents the current page).

Section titled “Additional props”
Section titled “NavigationRail.Footer”
Base element: <footer>

NavigationRail.Footer is typically used for grouping secondary actions list near the bottom of the NavigationRail, away from the main navigation items.

Example:

<NavigationRail.Content>
  <NavigationRail.List>…</NavigationRail.List>


  <NavigationRail.Footer>
    <NavigationRail.List>…</NavigationRail.List>
  </NavigationRail.Footer>
</NavigationRail.Content>
Section titled “Additional props”