Docs navigation · Material Next

Overview

<mnw-docs-vertical-tabs> lists sections or pages as Material Web link list items, with optional icons and a heading. This site's catalog on the left is one per group.
<mnw-docs-table-of-contents> lists the headings of the current page as plain links, with the current one marked. This site's "On this page" column is one.

Both take the same items, {label: string, href: string, icon?: string}, and are internal candidates: exported and used here, but their API may change before 1.0.

Live demo

Pick an item: navigate shows here.

The vertical tabs get their items from JavaScript, the table of contents from items-json. Both cancel navigate.

<div class="nav-demo">
  <mnw-docs-vertical-tabs heading="Components" aria-label="Components"></mnw-docs-vertical-tabs>
  <mnw-docs-table-of-contents
    heading="On this page"
    items-json='[{"label":"Overview","href":"#overview"},{"label":"Live demo","href":"#live-demo"},{"label":"API","href":"#api"}]'
  ></mnw-docs-table-of-contents>
</div>
<p class="demo-log" aria-live="polite">Pick an item: navigate shows here.</p>

import 'material-next-web-components/docs-table-of-contents.js';
import 'material-next-web-components/docs-vertical-tabs.js';
import type {MaterialNextDocsVerticalTabs} from 'material-next-web-components/docs-vertical-tabs.js';

export default (root: HTMLElement) => {
  const log = root.querySelector('.demo-log')!;
  const tabs = root.querySelector<MaterialNextDocsVerticalTabs>(
    'mnw-docs-vertical-tabs'
  )!;
  // From JavaScript, items is a property; items-json (above) suits server HTML.
  tabs.items = [
    {label: 'Code block', icon: 'code', href: '../code-block/'},
    {label: 'Tab bar', icon: 'tab', href: '../expressive-tab-bar/'},
    {label: 'App showcase', icon: 'apps', href: '../app-showcase/'},
  ];
  root.addEventListener('navigate', (event) => {
    const {index, item} = (event as CustomEvent).detail;
    // A single-page app cancels the link and routes itself.
    event.preventDefault();
    log.textContent = `navigate: index ${index}, ${item.href} (link canceled)`;
  });
};

Items: property or attribute

items is the JavaScript property. Use it from code.
items-json is a JSON string attribute, for HTML rendered on a server or by a static site generator, as this site does. Entries without a string label and href are dropped; invalid JSON leaves the current items.

Both defaults are placeholder links (to # anchors), so always set one of them.

Selection and events

A click makes the item active (activeIndex, and aria-current="page" on it) and fires navigate with {index, item}. The event bubbles out of the shadow root and is cancelable: call preventDefault() to stop the browser following the link and route in JavaScript. When you route yourself, also set activeIndex for changes that do not come from a click, such as Back or scrolling; this site's script does that for the table of contents.

API

`<mnw-docs-vertical-tabs>`

Vertical navigation list for documentation sections, built on Material Web list items. Each item is a link; the active one has aria-current="page".

<mnw-docs-vertical-tabs> properties
Property	Attribute	Type	Default	Description
`ariaLabel`	`aria-label`	`string`	`'Documentation sections'`	Accessible name of the navigation landmark.
`heading`	`heading`	`string`	`'Elements'`	Visible heading above the items; an empty string hides it.
`items`	Property only	`DocsNavigationItem[]`	`exampleNavigationItems`	The items, as `{label, href, icon?}` objects. JavaScript property. The default is three placeholder example links; always set it or `items-json`.
`activeIndex`	`active-index`	`number`	`0`	Index of the current item. Set by clicks; set it yourself when routing.
`itemsJson`	`items-json`	`string`	`''`	The items as a JSON string, for server-rendered HTML. Invalid JSON, or entries without a string `label` and `href`, are ignored.

<mnw-docs-vertical-tabs> events
Event	Description
`navigate`	`{index, item}` when an item is clicked, after it becomes active. Cancelable: `preventDefault()` keeps the browser from following the link, for routing in JavaScript.

`<mnw-docs-table-of-contents>`

"On this page" links for a documentation page. The active link has aria-current="page".

<mnw-docs-table-of-contents> properties
Property	Attribute	Type	Default	Description
`ariaLabel`	`aria-label`	`string`	`'Table of contents'`	Accessible name of the navigation landmark.
`heading`	`heading`	`string`	`'On this page'`	Visible heading above the items; an empty string hides it.
`items`	Property only	`DocsNavigationItem[]`	`exampleTableOfContentsItems`	The items, as `{label, href, icon?}` objects. JavaScript property. The default is four placeholder `#` anchors; always set it or `items-json`.
`activeIndex`	`active-index`	`number`	`0`	Index of the current item. Set by clicks; set it yourself when routing.
`itemsJson`	`items-json`	`string`	`''`	The items as a JSON string, for server-rendered HTML. Invalid JSON, or entries without a string `label` and `href`, are ignored.

<mnw-docs-table-of-contents> events
Event	Description
`navigate`	`{index, item}` when an item is clicked, after it becomes active. Cancelable: `preventDefault()` keeps the browser from following the link, for routing in JavaScript.

Accessibility

Each renders a <nav> named by aria-label. Give them distinct names when several are on a page, as this site does per catalog group.
The current item has aria-current="page".
Children you put inside the element are not shown once it renders; this site puts plain links there, which show before JavaScript runs and without it.

Limitations

Internal candidates: no compatibility promise before 1.0.
One level of items: there is no nesting or expand and collapse.