NavigationBar

The navigation bar makes it easy to switch between main pages on mobile devices.

Usage

Import the component:

import 'mdui/components/navigation-bar.js';
import 'mdui/components/navigation-bar-item.js';

Import the TypeScript type:

import type { NavigationBar } from 'mdui/components/navigation-bar.js';
import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js';

Example: (Note: The style="position: relative" in the example is for demonstration purposes. Don't include it in production.)

Item 1

Item 2

Item 3

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

Note:

By default, this component uses a position: fixed style and automatically adds a padding-bottom style to the body to prevent page content from being obscured. However, it uses a position: absolute style in the following cases:

When the scroll-target attribute is specified. In this case, padding-bottom is added to the specified element.
When it's inside the <mdui-layout></mdui-layout> component. In this case, padding-bottom is not added.

Examples

Label Visibility

With three or fewer items, labels in the navigation bar are always visible. When there are more than three items, only the selected item's label is shown.

Item 1

Item 2

Item 3

Item 1

Item 2

Item 3

Item 4

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

<br/>

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="directions_railway" value="item-3">Item 3</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-4">Item 4</mdui-navigation-bar-item>
</mdui-navigation-bar>

Source

The label-visibility attribute on <mdui-navigation-bar> controls the visibility of text labels. Possible values:

selected: Only the text of the selected item is displayed.
labeled: Text is always displayed.
unlabeled: Text is never displayed.

Item 1

Item 2

Item 3

selected

labeled

unlabeled

<mdui-navigation-bar value="item-1" label-visibility="selected" style="position: relative" class="example-label">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

<mdui-segmented-button-group value="selected" selects="single" style="margin-top: 16px">
  <mdui-segmented-button value="selected">selected</mdui-segmented-button>
  <mdui-segmented-button value="labeled">labeled</mdui-segmented-button>
  <mdui-segmented-button value="unlabeled">unlabeled</mdui-segmented-button>
</mdui-segmented-button-group>

<script>
  const navigationBar = document.querySelector(".example-label");
  const segmentedButtonGroup = navigationBar.nextElementSibling;

  segmentedButtonGroup.addEventListener("change", (event) => {
    navigationBar.labelVisibility = event.target.value;
  });
</script>

Source

In Container

By default, the navigation bar is fixed to the bottom of the viewport.

To place the navigation bar in a specific container, set the scroll-target attribute on <mdui-navigation-bar> to the CSS selector or DOM element for the scrollable container. In this case, the navigation bar is positioned relative to its parent element. You must add the styles position: relative; overflow: hidden to the parent element yourself.

Item 1

Item 2

Item 3

Page content

<div style="position: relative;overflow: hidden">
  <mdui-navigation-bar scroll-target=".example-scroll-target" value="item-1">
    <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
  </mdui-navigation-bar>

  <div class="example-scroll-target" style="height: 160px;overflow: auto;">
    <div style="height: 1000px">Page content</div>
  </div>
</div>

Source

Hide on Scroll

The scroll-behavior attribute on <mdui-navigation-bar> controls the visibility of the navigation bar during scrolling. Set its value to hide to hide the navigation bar when scrolling down and show it when scrolling up.

Use the scroll-threshold attribute to set how many pixels must be scrolled before the navigation bar starts hiding.

Item 1

Item 2

Item 3

Page content

<div style="position: relative;overflow: hidden">
  <mdui-navigation-bar
    scroll-behavior="hide"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior"
    value="item-1"
  >
    <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
  </mdui-navigation-bar>

  <div class="example-scroll-behavior" style="height: 160px;overflow: auto;">
    <div style="height: 1000px">Page content</div>
  </div>
</div>

Source

Icons

The icon attribute on <mdui-navigation-bar-item> sets the icon for the inactive state. The active-icon attribute sets the icon for the active state. Alternatively, use the icon and active-icon slots to set the icons for the inactive and active states.

Item 1

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item
    icon="place--outlined"
    active-icon="place"
    value="item-1"
  >Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item value="item-2">
    Item 2
    <mdui-icon slot="icon" name="people--outlined"></mdui-icon>
    <mdui-icon slot="active-icon" name="people"></mdui-icon>
  </mdui-navigation-bar-item>
</mdui-navigation-bar>

Source

Link

Use the href attribute on the <mdui-navigation-bar-item> component to turn the navigation item into a link. The download, target, and rel attributes are available for link-related functionality.

Item 1

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" href="https://www.mdui.org" target="_blank" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
</mdui-navigation-bar>

Source

Badge

You can add a badge to the <mdui-navigation-bar-item> component using the badge slot.

Item 1 99+

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">
    Item 1
    <mdui-badge slot="badge">99+</mdui-badge>
  </mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
</mdui-navigation-bar>

Source

Attribute	Property	Type	Default
`icon`	`icon`	`string`	-
Specifies the Material Icons name for the inactive state. Alternatively, use `slot="icon"`.
`active-icon`	`activeIcon`	`string`	-
Specifies the Material Icons name for the active state. Alternatively, use `slot="active-icon"`.
`value`	`value`	`string`	-
The value of the navigation item.
`href`	`href`	`string`	-
The URL for the link. When set, the component renders as an `<a>` element and supports link-related attributes.
`download`	`download`	`string`	-
Downloads the linked URL. Note: Only available when `href` is specified.
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
Controls where the linked URL opens. Possible values: `_blank`: Opens in a new tab or window. `_parent`: Opens in the parent browsing context, or `_self` if there is no parent. `_self`: Opens in the current browsing context (default). `_top`: Opens in the topmost browsing context, or `_self` if there are no ancestors. Note: Only available when `href` is specified.
`rel`	`rel`	`'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'`	-
Specifies the relationship of the linked URL as space-separated link types. Possible values: `alternate`: An alternate version of the current document. `author`: The author of the current document or article. `bookmark`: The permalink for the nearest ancestor section. `external`: The referenced document is not part of the same site as the current document. `help`: A link to context-sensitive help. `license`: Content covered by the copyright license described by the referenced document. `me`: Links to content owned by the current document's author. `next`: The next document in the series. `nofollow`: Not endorsed by the original author or publisher. `noreferrer`: Prevents the `Referer` header from being sent. Same effect as `noopener`. `opener`: Creates a new browsing context when the hyperlink would otherwise open in a top-level context that is not auxiliary (for example, when `target="_blank"` is specified). `prev`: The previous document in the series. `search`: Links to a resource that can be used to search through the current document and its related pages. `tag`: Marks the current document with the given tag. Note: Only available when `href` is specified.
`autofocus`	`autofocus`	`boolean`	`false`
Whether the element is focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
The element's tab order when navigating with the Tab key.

Name	Parameters	Returns
`click`		`void`
Simulates a mouse click on the element.
`focus`	`options: FocusOptions` (Optional)	`void`
Sets focus on the element. An optional object parameter may include a `preventScroll` property. If `preventScroll` is set to `true`, the page will not scroll to bring the focused element into view.
`blur`		`void`
Removes focus from the element.

Name
`focus`
Emitted when the navigation bar item gains focus.
`blur`
Emitted when the navigation bar item loses focus.

Name
(default)
Text.
`icon`
Icon.
`active-icon`
Icon for the active state.
`badge`
Badge.

Name
`container`
Container for the navigation item.
`indicator`
Indicator.
`badge`
Badge.
`icon`
Icon.
`active-icon`
Icon for the active state.
`label`
Text.

Name
`--shape-corner-indicator`
The corner radius of the indicator. You can use a specific pixel value, but it is recommended to reference design tokens.

Attribute	Property	Type	Default
`hide`	`hide`	`boolean`	`false`
Whether the navigation bar is hidden.
`label-visibility`	`labelVisibility`	`'auto' \| 'selected' \| 'labeled' \| 'unlabeled'`	`'auto'`
Specifies when the text is shown. Possible values: `auto`: Visible if there are 3 or fewer items; otherwise, only visible in the selected state. `selected`: Only visible in the selected state. `labeled`: Always visible. `unlabeled`: Never visible.
`value`	`value`	`string`	-
The value of the selected `<mdui-navigation-bar-item>`.
`scroll-behavior`	`scrollBehavior`	`'hide' \| 'shrink' \| 'elevate'`	-
Defines the scroll behavior. Possible values: `hide`: Hides when scrolling.
`scroll-target`	`scrollTarget`	`string \| HTMLElement \| JQ<HTMLElement>`	-
The element to watch for scroll events. Accepts a CSS selector, a DOM element, or a JQ object. Defaults to `window`.
`scroll-threshold`	`scrollThreshold`	`number`	-
The scroll distance (in pixels) required to trigger the scroll behavior.
`order`	`order`	`number`	-
Specifies the layout order within the `<mdui-layout>` component. Items are sorted in ascending order. The default value is `0`.

Name
`change`
Emitted when the value changes.
`show`
Emitted when the navigation bar starts to show. Can be prevented with `event.preventDefault()`.
`shown`
Emitted after the navigation bar has shown and animations are complete.
`hide`
Emitted when the navigation bar starts to hide. Can be prevented with `event.preventDefault()`.
`hidden`
Emitted after the navigation bar has hidden and animations are complete.

Name
(default)
Contains `<mdui-navigation-bar-item>` components.

Name
`--shape-corner`
The corner radius of the component. You can use a specific pixel value, but it is recommended to reference design tokens.
`--z-index`
The CSS `z-index` value of the component.

NavigationDrawer

NavigationBar

Usage

Examples

Label Visibility

In Container

Hide on Scroll

Icons

Link

Badge

`mdui-navigation-bar-item` API

Properties

Methods

Events

Slots

CSS Parts

CSS Custom Properties

`mdui-navigation-bar` API

Properties

Events

Slots

CSS Custom Properties