# Nav

> Navigation components for building various types of navigation interfaces, including tabs and pills.

Source: https://bootstrap-svelte.vercel.app/components/nav — part of the Bootstrap Svelte documentation (index: https://bootstrap-svelte.vercel.app/llms.txt).

## Basic Example

The default navigation component uses a `<ul>` with `<li>` items containing `<a>` links.

```html
<Nav.Root>
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Another Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

## Pills

Use the `itemStyle="pills"` prop to create a navigation with pills styling.

```html
<Nav.Root itemStyle="pills">
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Another Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

## Tabs

Use the `itemStyle="tabs"` prop to create a navigation with tabs styling.

```html
<Nav.Root itemStyle="tabs">
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Another Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

## Vertical Nav

Use the `verticalBreakpoint` prop to create a vertically stacked navigation. Set it to `"xs"` to make it always vertical.

```html
<Nav.Root verticalBreakpoint="xs">
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Another Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

## Fill and Justify

Force your `.nav`'s contents to extend the full available width with one of two options:

### Fill

Use `itemLayout="fill"` to proportionately fill all available space.

```html
<Nav.Root itemLayout="fill">
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Another Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

### Justified

Use `itemLayout="justified"` for equal-width elements.

```html
<Nav.Root itemLayout="justified">
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!">Another Link</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

## Horizontal Alignment

Use the `horizontalAlignment` prop to change the horizontal alignment of your nav. Default is "start", but you can use "center" or "end".

```html
<!-- Default (start) -->
<Nav.Root>
    <Nav.Item><Nav.Link href="#!">Default</Nav.Link></Nav.Item>
</Nav.Root>

<!-- Center aligned -->
<Nav.Root horizontalAlignment="center">
    <Nav.Item><Nav.Link href="#!">Center</Nav.Link></Nav.Item>
</Nav.Root>

<!-- End aligned -->
<Nav.Root horizontalAlignment="end">
    <Nav.Item><Nav.Link href="#!">End</Nav.Link></Nav.Item>
</Nav.Root>
```

## Different Element Types

The Nav component can be rendered as different HTML elements using the `as` prop. The default is `"ul"`, but you can also use `"ol"` or `"nav"`.

```html
<!-- Default (UL) -->
<Nav.Root>
    <Nav.Item><Nav.Link href="#!">Link</Nav.Link></Nav.Item>
</Nav.Root>

<!-- As OL -->
<Nav.Root elementType="ol">
    <Nav.Item><Nav.Link href="#!">Link</Nav.Link></Nav.Item>
</Nav.Root>

<!-- As NAV -->
<Nav.Root elementType="nav">
    <Nav.Link href="#!">Link</Nav.Link>
</Nav.Root>
```

## Active State Management

The Nav component supports two modes for managing active states:

### Explicit Control

When you provide the `isActive` prop, you have full control over the active state. This is useful when integrating with routing libraries or when you need precise control.

- Explicitly Active
- Explicitly Inactive
- Disabled

### Internal Management

When you don't provide the `isActive` prop (or set it to `undefined`), the component manages the active state internally. Clicking a link will make it active and deactivate others in the same nav.

⚠️ **NOTE**: In order for the internal state management to work properly, ensure that the `href` prop is set to a unique value for each.

```html
<!-- Explicit Active State Control -->
<Nav.Root>
    <Nav.Item>
        <Nav.Link href="#!" isActive={true}>Explicitly Active</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#!" isActive={false}>Explicitly Inactive</Nav.Link>
    </Nav.Item>
</Nav.Root>

<!-- Internal Active State Management -->
<Nav.Root>
    <Nav.Item>
        <Nav.Link href="#nav-link-1">Click to Activate</Nav.Link>
    </Nav.Item>
    <Nav.Item>
        <Nav.Link href="#nav-link-2">Another Link</Nav.Link>
    </Nav.Item>
</Nav.Root>
```

## Tabs with Content

For dynamic tabbed interfaces, use the Nav component with the Tab component. See the [Tab documentation](https://bootstrap-svelte.vercel.app/components/tab) for more details.

## API Reference

### Nav.Root Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaOrientation` | `'horizontal' \| 'vertical'` | - | ARIA orientation attribute. Automatically set to 'vertical' when verticalBreakpoint is defined. |
| `as` | `'nav' \| 'ol' \| 'ul'` | `'ul'` | Element type to render |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `horizontalAlignment` | `'start' \| 'center' \| 'end'` | `'start'` | Horizontal alignment for the nav items |
| `id` | `string` | Auto-generated | Unique identifier for the nav |
| `itemLayout` | `'fill' \| 'justified'` | - | Layout strategy for the nav items |
| `itemStyle` | `'pills' \| 'tabs' \| 'underline'` | - | Visual style for the nav items |
| `role` | `'navigation' \| 'tablist' \| null` | Auto-determined | ARIA role. Defaults to 'tablist' if itemStyle is 'tabs', 'navigation' for non-nav elements, null otherwise |
| `verticalBreakpoint` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | - | Breakpoint at which the nav becomes vertical. 'xs' means always vertical. |

### Nav.Item Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |

### Nav.Link Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `href` | `string` | `'#!'` | URL for the link. The exclamation point is used to prevent auto-scrolling to the top of the page. |
| `id` | `string` | Auto-generated | Unique identifier for the link |
| `isActive` | `boolean \| undefined` | `undefined` | Whether the link is active. When provided, overrides internal state management. When undefined, the component manages active state internally based on user interactions. |
| `isDisabled` | `boolean` | `false` | Whether the link is disabled |
| `role` | `'button' \| 'tab'` | Auto-determined | ARIA role for the link. Defaults to 'tab' if within tablist context. |

### CSS Classes

The component applies Bootstrap's nav classes based on the provided props:

- `nav` - Base class for the Nav component
- `nav-item` - Applied to Nav.Item components
- `nav-link` - Applied to Nav.Link components
- `nav-pills` - Applied when itemStyle="pills"
- `nav-tabs` - Applied when itemStyle="tabs"
- `nav-underline` - Applied when itemStyle="underline"
- `nav-fill` - Applied when itemLayout="fill"
- `nav-justified` - Applied when itemLayout="justified"
- `flex-column` - Applied when verticalBreakpoint="xs"
- `flex-{breakpoint}-column` - Applied for other verticalBreakpoint values
- `justify-content-center` - Applied when horizontalAlignment="center"
- `justify-content-end` - Applied when horizontalAlignment="end"
- `active` - Applied to Nav.Link when isActive=true
- `disabled` - Applied to Nav.Link when isDisabled=true