# Navigation Bar
A navigation bar lets people switch between a small number of top-level destinations, and can hide as the page scrolls.
**Example: A navigation bar with four destinations and Home active**
```html
home
Home
explore
Explore
library_music
Library
person
Profile
```
## Usage guidelines
* **Use it in compact and medium windows.** From expanded windows up, switch to a [navigation rail](/material-web/3.0/components/navigation-rail/).
* **Keep three to five destinations.** They should be of equal importance.
* **Keep destinations consistent.** The same destinations appear on every screen of the app.
* **Pick the item layout.** Use [vertical](#item-layout) items in compact windows and horizontal items from medium windows.
This component is new in [M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive).
## Anatomy
A navigation bar holds items. Each item has an icon, a label and an optional badge.
**Example: A navigation bar with one item that has an icon, a badge and a label**
```html
chat_bubble
3
Chats
call
Calls
```
## Examples
### Item layout
Set `item-layout` to `vertical` (the default) or `horizontal`. With `auto`, items are vertical in compact windows and horizontal from 600px.
**Example: A navigation bar with horizontal items**
```html
auto_awesome
For you
bookmark
Saved
settings
Settings
```
### Badges
Set `badge` on an item to show a count, or `badge="dot"` for a small dot that signals something new.
**Example: Navigation bar items with a count badge and a dot badge**
```html
mail
Inbox
chat_bubble
Chat
videocam
Meet
```
### Links
Give an item an `href` (and optionally `target` and `rel`) to make the destination a link, as in the first example. The item then has the `link` role and the selected one is marked `aria-current="page"`. Without `href` an item is a tab that just reports the selection.
### Hide on scroll
Set `scroll-behavior="hide"` to hide the bar when the page scrolls down and show it again on scroll up. By default it follows the window; set `scroll-target` to the id of another scrolling element. Fix the bar to the bottom of the page.
**Example: A navigation bar that hides while its list scrolls down**
*HTML*
```html
Message 1
Message 2
Message 3
Message 4
Message 5
Message 6
Message 7
Message 8
inbox
Inbox
send
Sent
```
*CSS*
```css
#messages {
inline-size: 100%;
block-size: 240px;
overflow: auto;
}
md-gb-nav-bar {
position: sticky;
inset-block-end: 0;
}
```
### Selection
The `active` item shows the current destination, and `selected-index` selects an item by position. The bar fires `change` when the selection changes.
**Example: A navigation bar that reports the selected index**
*HTML*
```html
home
Home
search
Search
settings
Settings
```
*TypeScript*
```ts
const bar = document.querySelector('md-gb-nav-bar')!;
const selection = document.querySelector('#selection')!;
bar.addEventListener('change', () => {
selection.textContent = 'Selected item ' + bar.selectedIndex;
});
```
## Accessibility
* Give the bar an `aria-label` such as "Primary navigation".
* Without links the bar is a tab list and its items are tabs, with exactly one selected. Tab moves focus into the bar, the arrow keys move between items, and Enter and Space select one.
* When the items have an `href` the bar is a navigation landmark of links and the selected one is `aria-current="page"`. Enter follows a link; Space doesn't.
* Every item needs a visible label, which is also its accessible name. If the label is ambiguous, add a more descriptive `aria-label` to the item.
* A hidden bar never hides while focus is inside it or when the page scrolls from a key press, and it reappears when focus moves into it. Leave `scroll-behavior` off if screen reader users rely on the bar.
* Disabled items leave the tab order.
## API reference
### <md-gb-nav-bar>
A Material Design gBreeze navigation bar custom element.
#### Properties
| Property | Attribute | Type | Default |
| --- | --- | --- | --- |
| autoSelect
Whether or not to automatically select a tab when it is focused. | autoselect | boolean | false |
| itemLayout
The layout orientation of items: vertical, horizontal, or auto (vertical in compact windows, horizontal from medium windows, 600px). | item-layout | NavBarLayout | 'vertical' |
| orientation
Orientation of the tablist ('horizontal' or 'vertical'). | orientation | "horizontal" | "vertical" | 'horizontal' |
| scrollBehavior
How the bar reacts to scrolling: hide hides it on scroll down. | scroll-behavior | "hide" | |
| scrollTarget
The id of the element whose scrolling drives scroll-behavior. Defaults to the window. | scroll-target | string | '' |
| selectedIndex
The 0-based index of the currently active navigation bar item. Alias for selectedTabIndex. | selected-index | number | |
| selectedTabIndex
The index of the currently selected tab. | selectedtabindex | number | |
#### Slots
| Slot | Description |
| --- | --- |
| default | Used to display navigation bar items (md-gb-nav-bar-item). |
#### Events
| Event | Description |
| --- | --- |
| change
Event | Fired when the selected navigation bar item changes. |
#### CSS parts
| Part | Description |
| --- | --- |
| ::part(nav-bar) | The navigation bar's root container. |
#### CSS custom properties
| Property | Description |
| --- | --- |
| --container-color | |
| --container-elevation | |
| --container-height | |
| --container-shadow-color | |
| --container-shape | |
| --item-active-icon-color | |
| --item-active-indicator-color | |
| --item-active-indicator-height | |
| --item-active-indicator-icon-label-space | |
| --item-active-indicator-leading-space | |
| --item-active-indicator-shape | |
| --item-active-indicator-trailing-space | |
| --item-active-indicator-width | |
| --item-active-label-text-color | |
| --item-active-state-layer-color | |
| --item-between-space | |
| --item-container-between-space | |
| --item-icon-size | |
| --item-inactive-icon-color | |
| --item-inactive-label-text-color | |
| --item-inactive-state-layer-color | |
| --item-label-text | |
| --item-label-text-axes | |
| --item-label-text-tracking | |
| --motion-duration | |
| --motion-easing | |
### <md-gb-nav-bar-item>
A Material Design gBreeze navigation bar item custom element.
#### Properties
| Property | Attribute | Type | Default |
| --- | --- | --- | --- |
| active
Whether the navigation bar item is active. Alias for selected. | active | boolean | |
| badge
Optional badge text (or 'dot' / 'true' for a small dot badge). | badge | string | '' |
| disabled
Whether the navigation bar item is disabled. | disabled | boolean | false |
| href
The URL the destination links to. The item is then a link (role link, aria-current="page" while selected) instead of a tab. | href | string | '' |
| itemLayout
The layout orientation of the item ('vertical' or 'horizontal'). | item-layout | NavBarItemLayout | 'vertical' |
| label
Optional label text if not provided via default slot. | label | string | '' |
| rel
The link's rel attribute, when href is set. | rel | string | '' |
| tabpanel
ID of the associated md-aria-tabpanel element. | tabpanel | string | |
| target
Where to open the linked href, e.g. _blank. | target | "" | "_blank" | "_parent" | "_self" | "_top" | '' |
| unfilledIcon
Whether the icon has no filled style. The active destination then uses the semibold icon weight instead of the filled icon. | unfilled-icon | boolean | false |
#### Slots
| Slot | Description |
| --- | --- |
| default | Used to display the item's label text. |
| badge | Used to display a custom badge on the item's icon. |
| icon | Used to display the item's icon (md-gb-icon). |
#### Methods
| Method | Description |
| --- | --- |
| click
() => void | Activates the destination: follows its link, else clicks the tab. |
#### CSS parts
| Part | Description |
| --- | --- |
| ::part(indicator) | The active indicator / icon container element. |
| ::part(label) | The label text container element. |
| ::part(nav-bar-item) | The navigation bar item's presentational container. |