The m3e-nav-rail extends Nav Bar to provide a vertical bar, typically used on larger devices, that allows a user to switch between views.

npm i @m3e/nav-rail

This section outlines usage examples and configuration guidance for the components in this package.

The m3e-nav-rail supports three modes: compact (default), expanded, and auto. In a compact mode, items are oriented vertically. When extended, items are oriented horizontally. Using auto, the orientation is responsive and determined by viewport size. Use the mode attribute to change a bar's mode.

The following example illustrates a common layout.

• A m3e-icon-button is used in conjunction with the m3e-nav-rail-toggle to provide a toggle button used to toggle between modes. The for attribute designates the rail to toggle.
• An extended m3e-fab will automatically transition to reflect the mode of the rail.
• Top-level destinations are specified using m3e-nav-item from the Nav Bar package.

<m3e-nav-rail id="nav-rail">
  <m3e-icon-button toggle>
    <m3e-icon name="menu"></m3e-icon>
    <m3e-icon slot="selected" name="menu_open"></m3e-icon>
    <m3e-nav-rail-toggle for="nav-rail"></m3e-nav-rail-toggle>
  </m3e-icon-button>
  <m3e-fab size="small">
    <m3e-icon name="edit"></m3e-icon>
    <span slot="label">Extended</span>
  </m3e-fab>
  <m3e-nav-item><m3e-icon slot="icon" name="news"></m3e-icon>News</m3e-nav-item>
  <m3e-nav-item><m3e-icon slot="icon" name="globe"></m3e-icon>Global</m3e-nav-item>
  <m3e-nav-item><m3e-icon slot="icon" name="star"></m3e-icon>For you</m3e-nav-item>
  <m3e-nav-item><m3e-icon slot="icon" name="newsstand"></m3e-icon>Trending</m3e-nav-item>
</m3e-nav-rail>

As illustrated above, items are specified using the m3e-nav-item component. Use the default slot to specify an item's label and use the icon slot to specify an icon.

<m3e-nav-item><m3e-icon slot="icon" name="news"></m3e-icon>News</m3e-nav-item>

The m3e-nav-rail only supports single-select. Use the selected attribute of m3e-nav-item to specify which item in a rail is selected. When clicked, a cancellable input event is emitted followed by a change event. To cancel selection change, call preventDefault during input.

In addition, you can use the selected-icon slots to specify an alternate icon when selected. When using the m3e-icon to present icons, the icon will automatically be filled when an item is selected.

Use the disabled attribute to disable an item. By default, disabled items are not focusable with the keyboard. You can use the disabled-interactive attribute to support focusability of disabled controls to increase their discoverability.

Items can also behave like links by specifying a URL using the href attribute. You can also specify target, rel and download similar to native anchor tags.

Navigation rails are given ARIA role="navigation", indicating that the region serves as a navigational landmark and helps assistive technologies identify it as a container for site or app navigation links. Always provide an accessible label via aria-label or aria-labelledby.

Items are given the ARIA role button, indicating they are clickable elements that trigger actions and aria-current="true" is used to convey the selected state.

Icons slots have aria-hidden="true" to ensure icons are always hidden from assistive technologies.

When disabling using either the disabled or disabled-interactive attribute, aria-disabled="true" is used to convey to assistive technologies that the item is disabled. If disabled using disabled-interactive, tabindex is retained to convey that the item continues to be interactive.

When href is specified, the ARIA role link is used instead of button to convey the item provides an interactive reference to a resource. In addition, the component presents an internal anchor, hidden from assistive technologies, used to invoke native browser features such a context menu options and tooltips.

Rail toggles use aria-controls to associate its parenting element with the rail, and dynamically update aria-expanded to indicate whether the rail is expanded.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/nav-rail/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/a11y": "/node_modules/@m3e/core/dist/a11y.js",
      "@m3e/core/layout": "/node_modules/@m3e/core/dist/layout.js",
      "@m3e/nav-bar": "/node_modules/@m3e/nav-bar/dist/index.js"
    }
  }
</script>

For production, use index.min.js, a11y.min.js, and layout.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.