# Navigation Menu Documentation
A list of links that allow users to navigate between pages of a website.
This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.
```svelte
{#snippet ListItem({ className, title, content, href }: ListItemProps)}
{title}
{content}
{/snippet}
Getting started
Bits UI
The headless components for Svelte.
{@render ListItem({
href: "/docs",
title: "Introduction",
content: "Headless components for Svelte and SvelteKit"
})}
{@render ListItem({
href: "/docs/getting-started",
title: "Getting Started",
content: "How to install and use Bits UI"
})}
{@render ListItem({
href: "/docs/styling",
title: "Styling",
content: "How to style Bits UI components"
})}
```
## Structure
```svelte
```
## Usage
### Vertical
You can create a vertical menu by using the `orientation` prop.
```svelte
```
### Flexible Layouts
Use the `Viewport` component when you need extra control over where `Content` is rendered. This can be useful when your design requires an adjusted DOM structure or if you need flexibility to achieve advanced animations. Tab focus will be managed automatically.
```svelte
Item oneItem one contentItem twoItem two content
```
### With Indicator
You can use the optional `Indicator` component to highlight the currently active `Trigger`, which is useful when you want to provide an animated visual cue such as an arrow or highlight to accompany the `Viewport`.
```svelte
Item oneItem one contentItem twoItem two content
```
### Submenus
You can create a submenu by nesting your navigation menu and using the `Navigation.Sub` component in place of `NavigationMenu.Root`. Submenus work differently than the `Root` menus and are more similar to [Tabs](/docs/components/tabs) in that one item should always be active, so be sure to assign and pass a `value` prop.
```svelte
Item oneItem one contentItem twoSub item oneSub item one contentSub item twoSub item two content
```
### Advanced Animation
We expose `--bits-navigation-menu-viewport-[width|height]` and `data-motion['from-start'|'to-start'|'from-end'|'to-end']` to allow you to animate the `NavigationMenu.Viewport` size and `NavigationMenu.Content` position based on the enter/exit direction.
Combining these with `position: absolute;` allows you to create smooth overlapping animation effects when moving between items.
```svelte
Item one
Item one content
Item two
Item two content
```
```css
/* app.css */
.NavigationMenuContent {
position: absolute;
top: 0;
left: 0;
animation-duration: 250ms;
animation-timing-function: ease;
}
.NavigationMenuContent[data-motion="from-start"] {
animation-name: enter-from-left;
}
.NavigationMenuContent[data-motion="from-end"] {
animation-name: enter-from-right;
}
.NavigationMenuContent[data-motion="to-start"] {
animation-name: exit-to-left;
}
.NavigationMenuContent[data-motion="to-end"] {
animation-name: exit-to-right;
}
.NavigationMenuViewport {
position: relative;
width: var(--bits-navigation-menu-viewport-width);
height: var(--bits-navigation-menu-viewport-height);
transition:
width,
height,
250ms ease;
}
@keyframes enter-from-right {
from {
opacity: 0;
transform: translateX(200px);
}
to {
opacity: 1;
transform: translateX(0);
}
}
@keyframes enter-from-left {
from {
opacity: 0;
transform: translateX(-200px);
}
to {
opacity: 1;
transform: translateX(0);
}
}
@keyframes exit-to-right {
from {
opacity: 1;
transform: translateX(0);
}
to {
opacity: 0;
transform: translateX(200px);
}
}
@keyframes exit-to-left {
from {
opacity: 1;
transform: translateX(0);
}
to {
opacity: 0;
transform: translateX(-200px);
}
}
```
### Force Mounting
You may wish for the links in the Navigation Menu to persist in the DOM, regardless of whether the menu is open or not. This is particularly useful for SEO purposes. You can achieve this by using the `forceMount` prop on the `NavigationMenu.Content` and `NavigationMenu.Viewport` components.
##### Warning
**Note:** Using `forceMount` requires you to manage the visibility of the elements yourself, using the `data-state` attributes on the `NavigationMenu.Content` and `NavigationMenu.Viewport` components.
```svelte
```
```svelte
{#snippet ListItem({ className, title, content, href }: ListItemProps)}
{title}
{content}
{/snippet}
Getting started
Bits UI
The headless components for Svelte.
{@render ListItem({
href: "/docs",
title: "Introduction",
content: "Headless components for Svelte and SvelteKit"
})}
{@render ListItem({
href: "/docs/getting-started",
title: "Getting Started",
content: "How to install and use Bits UI"
})}
{@render ListItem({
href: "/docs/styling",
title: "Styling",
content: "How to style Bits UI components"
})}
```
## API Reference
### NavigationMenu.Root
The root navigation menu component which manages & scopes the state of the navigation menu.
| Property | Type | Description |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` $bindable | `string` | The value of the currently active menu.`Default: undefined` |
| `onValueChange` | `function`- (value: string) => void | A callback function called when the active menu value changes.`Default: undefined` |
| `dir` | `enum`- 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` |
| `skipDelayDuration` | `number` | How much time a user has to enter another trigger without incurring a delay again.`Default: 300` |
| `delayDuration` | `number` | The duration from when the mouse enters a trigger until the content opens.`Default: 200` |
| `orientation` | `enum`- 'horizontal' \| 'vertical' | The orientation of the menu.`Default: horizontal` |
| `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.List
A menu within the menubar.
| Property | Type | Description |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLUListElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.Item
A list item within the navigation menu.
| Property | Type | Description |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string` | The value of the item.`Default: undefined` |
| `ref` $bindable | `HTMLLiElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.Trigger
The button element which toggles the dropdown menu.
| Property | Type | Description |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean` | Whether or not the trigger is disabled.`Default: false` |
| `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.Content
The content displayed when the dropdown menu is open.
| Property | Type | Description |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInteractOutside` | `function`- (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: undefined` |
| `onFocusOutside` | `function`- (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: undefined` |
| `interactOutsideBehavior` | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default: undefined` |
| `escapeKeydownBehavior` | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` |
| `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` |
| `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.Link
A link within the navigation menu.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active` | `boolean` | Whether or not the link is active.`Default: false` |
| `onSelect` | `function`- () => void | A callback function called when the link is selected.`Default: undefined` |
| `ref` $bindable | `HTMLAnchorElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.Viewport
The viewport element for the navigation menu, which is used to contain the menu items.
| Property | Type | Description |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` |
| `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | ### NavigationMenu.Indicator
The indicator element for the navigation menu, which is used to indicate the current active item.
| Property | Type | Description |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` |
| `ref` $bindable | `HTMLSpanElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` |
| `children` | `Snippet` | The children content to render.`Default: undefined` |
| `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` |