The m3e-nav-bar is a horizontal bar, typically used on smaller devices, that allows a user to switch between 3-5 views.

npm i @m3e/nav-bar

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

The m3e-nav-bar supports three modes: compact (default), expanded, and auto. In a compact mode, items are oriented vertically and fill the available space of the bar. When extended, items are oriented horizontally and are centered within the bar. 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 both compact and extended modes.

<m3e-nav-bar mode="compact">
  <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-bar>
<br />
<m3e-nav-bar mode="extended">
  <!-- Items omitted for brevity -->
</m3e-nav-bar>

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-bar only supports single-select. Use the selected attribute of m3e-nav-item to specify which item in a bar 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.

<m3e-nav-bar>
  <m3e-nav-item selected><m3e-icon slot="icon" name="news"></m3e-icon>News</m3e-nav-item>
  <!-- Additional items omitted for brevity -->
</m3e-nav-bar>

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.

<m3e-nav-bar>
  <m3e-nav-item disabled><m3e-icon slot="icon" name="news"></m3e-icon>News</m3e-nav-item>
  <m3e-nav-item disabled-interactive><m3e-icon slot="icon" name="globe"></m3e-icon>Global</m3e-nav-item>
  <!-- Additional items omitted for brevity -->
</m3e-nav-bar>

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.

<m3e-nav-bar>
  <m3e-nav-item href="https://www.google.com" target="_blank">
    <m3e-icon slot="icon" name="news"></m3e-icon>News
  </m3e-nav-item>
</m3e-nav-bar>

Navigation bars 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.

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-bar/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"
    }
  }
</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.