NavigationBar

The navigation bar facilitates easy switching 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. Remove it in actual use.)

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

Text labels in the navigation bar are always visible when there are 3 or fewer navigation items. If there are more than 3 items, only the text of the selected item is displayed.

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>

Code

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>

Code

In Container

By default, the navigation bar is relative to the current window and appears at the bottom of the page.

If you want to place the navigation bar within a specific container, use the scroll-target attribute on <mdui-navigation-bar>. The value should be the CSS selector or DOM element of the container with scrollable content. In this case, the navigation bar will be relative to the parent element. You need to manually add the styles position: relative; overflow: hidden to the parent element.

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>

Code

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.

The scroll-threshold attribute sets the number of pixels to start hiding the navigation bar.

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>

Code

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>

Code

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>

Code

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>

Code

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 hyperlink. If specified, the component renders as an `<a>` element and can use link-related attributes.
`download`	`download`	`string`	-
Instructs the browser to treat the linked URL as a download. Note: This is only available when `href` is specified.
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
Defines where to display the linked URL. Possible values: `_blank`: Opens in a new tab or window. `_parent`: Opens in the parent browsing context or `_self` if no parent exists. `_self`: Opens in the current browsing context. (Default). `_top`: Opens in the topmost browsing context or `_self` if no ancestors exist. Note: This is 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`: Alternate versions of the current document. `author`: Author of the current document or article. `bookmark`: Permanent link for the nearest ancestor section. `external`: The referenced document is not part of the same site as the current document. `help`: Link to context-sensitive help. `license`: Indicates that the main content of the current document is covered by the copyright license described by the referenced document. `me`: Indicates that the current document represents the person who owns the linked content. `next`: Indicates that the current document is part of a series and the next document in the series is the referenced document. `nofollow`: Indicates that the current document's original author or publisher does not endorse the referenced document. `noreferrer`: No `Referer` header will be included. Also has the same effect as `noopener`. `opener`: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "`_blank`" as `target` attribute value). `prev`: Indicates that the current document is part of a series and the previous document in the series is the referenced document. `search`: Links to a resource that can be used to search through the current document and its related pages. `tag`: Gives a tag (identified by the given address) that applies to the current document. Note: This is only available when `href` is specified.
`autofocus`	`autofocus`	`boolean`	`false`
Determines if the element should be focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
Specifies the order in which the element receives focus 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 parameter can be an object with 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 size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.

Attribute	Property	Type	Default
`hide`	`hide`	`boolean`	`false`
Hides the navigation bar when set.
`label-visibility`	`labelVisibility`	`'auto' \| 'selected' \| 'labeled' \| 'unlabeled'`	`'auto'`
Specifies the visibility of the text. Possible values: `auto`: Visible if there are 3 or fewer options, otherwise only the selected state is visible. `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 that listens for scroll events. Accepts a CSS selector, DOM element, or JQ object. Defaults to `window`.
`scroll-threshold`	`scrollThreshold`	`number`	-
The scroll distance (in pixels) that triggers 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 size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
`--z-index`
The CSS `z-index` value of the component.

Up Next

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