# Navs and tabs

Use the nav shortcode to show a group of multiple tab panes.

## Overview

Added in v0.11.8

Use the `nav` shortcode to show a group of multiple tab panes. Add `nav-item` inner elements for each tab pane.

### Horizontal alignment

By default, navs are left-aligned, but you can easily change them to center or right aligned.

Centered with `.justify-content-center`:

```markdown
{{< nav class="justify-content-center" >}}
  {{< nav-item title="Nav Item #1" show="true" />}}
  {{< nav-item title="Nav Item #2" />}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

Right-aligned with `.justify-content-end`:

```markdown
{{< nav class="justify-content-end" >}}
  {{< nav-item title="Nav Item #1" show="true" />}}
  {{< nav-item title="Nav Item #2" />}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Vertical

Stack your navigation by setting `vertical` to `true`.

```markdown
{{< nav vertical="true" id="vertical-1" >}}
  {{< nav-item title="Nav Item #1" show="true" >}}
    This is the first item's nav body. It supports Markdown content. The item is shown by adding
    the value `show` to the `class` argument.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #2" >}}
    This is the second item's nav body. It too supports HTML content.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Tabs

Takes the basic nav from above and generates a tabbed interface by setting `type` to `tabs`. The inner content of each `nav-item` is rendered within a linked tab pane. The content supports embedded HTML.

```markdown
{{< nav tab-type="tabs" id="tabs-1" >}}
  {{< nav-item title="Nav Item #1" show="true" >}}
    This is the first item's nav body. It supports Markdown content. The item is shown by adding
    the value `show` to the `class` argument.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #2" >}}
    This is the second item's nav body. It too supports HTML content.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Pills

Take that same HTML, but using `pills` instead:

```markdown
{{< nav tab-type="pills" id="pills-1" >}}
  {{< nav-item title="Nav Item #1" show="true" >}}
    This is the first item's nav body. It supports Markdown content. The item is shown by adding
    the value `show` to the `class` argument.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #2" >}}
    This is the second item's nav body. It too supports HTML content.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Underline

Take that same HTML, but using `underline` instead:

```markdown
{{< nav tab-type="underline" id="underline-1" >}}
  {{< nav-item title="Nav Item #1" show="true" >}}
    This is the first item's nav body. It supports Markdown content. The item is shown by adding
    the value `show` to the `class` argument.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #2" >}}
    This is the second item's nav body. It too supports HTML content.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Callout

Added in v0.21.0

Take that same HTML, but using `callout` instead:

```markdown
{{< nav tab-type="callout" id="callout-1" >}}
  {{< nav-item title="Nav Item #1" show="true" >}}
    This is the first item's nav body. It supports Markdown content. The item is shown by adding
    the value `show` to the `class` argument.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #2" >}}
    This is the second item's nav body. It too supports HTML content.
  {{< /nav-item >}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Buttons

Added in v2.7.0

Use `tab-type="buttons"` to render a compact button group instead of a standard nav. Set the `icon` argument on each `nav-item` to display an icon-only button; the `title` is then used as the tooltip and `aria-label`. This variant is well suited for view-toggle controls.

```markdown
{{< nav tab-type="buttons" id="buttons-1" >}}
  {{< nav-item title="Grid view" icon="grid" show="true" >}}
    Content shown in grid layout.
  {{< /nav-item >}}
  {{< nav-item title="List view" icon="list-ul" >}}
    Content shown in list layout.
  {{< /nav-item >}}
{{< /nav >}}
```

### Alignment

Added in v2.7.0

Use the `align` argument to control the horizontal alignment of the nav controls. Supported values are `start` (default), `center`, and `end`. The argument is ignored when `vertical` is set.

```markdown
{{< nav tab-type="pills" align="center" id="align-center-1" >}}
  {{< nav-item title="Nav Item #1" show="true" />}}
  {{< nav-item title="Nav Item #2" />}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

```markdown
{{< nav tab-type="pills" align="end" id="align-end-1" >}}
  {{< nav-item title="Nav Item #1" show="true" />}}
  {{< nav-item title="Nav Item #2" />}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

### Controls placement

Added in v2.7.0

Use `controls-placement="bottom"` to render the nav controls below the tab content instead of above.

```markdown
{{< nav tab-type="buttons" controls-placement="bottom" id="placement-1" >}}
  {{< nav-item title="Grid view" icon="grid" show="true" >}}
    Content shown in grid layout.
  {{< /nav-item >}}
  {{< nav-item title="List view" icon="list-ul" >}}
    Content shown in list layout.
  {{< /nav-item >}}
{{< /nav >}}
```

### Fill and justify

To proportionately fill all available space with your `.nav-items`, use `.nav-fill`. Notice that all horizontal space is occupied, but not every nav item has the same width.

```markdown
{{< nav tab-type="pills" class="nav-fill" >}}
  {{< nav-item title="Nav Item #1" show="true" />}}
  {{< nav-item title="Much longer nav item #2" />}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

For equal-width elements, use `.nav-justified`. All horizontal space will be occupied by nav links, but unlike the `.nav-fill` above, every nav item will be the same width.

```markdown
{{< nav tab-type="pills" class="nav-justified" >}}
  {{< nav-item title="Nav Item #1" show="true" />}}
  {{< nav-item title="Much longer nav item #2" />}}
  {{< nav-item title="Nav Item #3" disabled="true" />}}
{{< /nav >}}
```

## Styling

The file `assets/scss/components/_nav.scss` defines the Hinode-specific styling of the `nav` shortcode. Check the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/components/navs-tabs/#css) for additional styling options.

```scss
.nav-tabs {
    border: none !important;
}

.nav-callout, .tab-content {
    --#{$prefix}nav-callout-bg: var(--#{$prefix}body-bg);
    --#{$prefix}nav-callout-active-bg: var(--bs-primary-bg-subtle);
    --#{$prefix}nav-callout-gap: #{$nav-underline-gap};

    column-gap: var(--#{$prefix}nav-callout-gap) !important;
}

.nav-callout + .tab-content {
    background-color: var(--#{$prefix}nav-callout-bg);
    padding: 2 * $spacer;
    margin-top: 0 !important;
}

.nav-callout .nav-link {
    display: flex;
    text-align: start;
    vertical-align: text-top;
    border-radius: 0;
    padding: 0 0 (4 * $spacer);
    border-bottom: none;
    position: relative;
}

.nav-callout .nav-link.active {
    background-image: linear-gradient(to top right, var(--#{$prefix}nav-callout-bg) 50%, transparent 0);
    background-size: 50% (3 * $spacer);
    background-repeat: no-repeat;
    background-position: 50% bottom;
    font-weight: 600;
    color: var(--bs-nav-underline-link-active-color);

    // Diagonal border line
    &::before {
        content: "";
        position: absolute;
        bottom: 0;
        left: 25%;
        width: 50%;
        height: (3 * $spacer);
        background: linear-gradient(
            to top right,
            transparent calc(50% - 0.5px),
            var(--#{$prefix}border-color) calc(50% - 0.5px),
            var(--#{$prefix}border-color) calc(50% + 0.5px),
            transparent calc(50% + 0.5px)
        );
        pointer-events: none;
    }

    // Left border only
    &::after {
        content: "";
        position: absolute;
        bottom: 0;
        left: 25%;
        width: 50%;
        height: (3 * $spacer);
        border-left: 1px solid var(--#{$prefix}border-color);
        pointer-events: none;
    }
}

.nav-callout .accordion-button {
    background-color: var(--#{$prefix}nav-callout-bg) !important;
    border: solid;
    border-color: var(--#{$prefix}border-color);
    border-radius: var(--#{$prefix}accordion-inner-border-radius) !important;
    margin-bottom: 0;

    &:focus {
        border-bottom: none !important;
        box-shadow: none;
    }

    &:not(.collapsed) {
        box-shadow: none;
    }
}

.nav-callout .accordion-item {
    margin-top: 2 * $spacer;
    margin-bottom: 2 * $spacer;
    border: none;
}

.nav-callout .accordion-button[aria-expanded="false"] {
    border-bottom: solid !important;
    border-color: var(--#{$prefix}border-color) !important;
    border-radius: var(--#{$prefix}accordion-inner-border-radius);
}

.nav-callout .accordion-button[aria-expanded="true"] {
    border-color: var(--#{$prefix}border-color) !important;
    border-bottom: none !important;
    border-radius: var(--#{$prefix}accordion-inner-border-radius) var(--#{$prefix}accordion-inner-border-radius) 0 0 !important;
    padding-bottom: 3 * $spacer;
    background-image: linear-gradient(to top right, var(--#{$prefix}nav-callout-active-bg) 50%, transparent 0);
    background-size: 10% (2.5 * $spacer);
    background-repeat: no-repeat;
    background-position: 10% bottom;
}

.nav-callout .accordion-collapse {
    background-color: var(--#{$prefix}nav-callout-active-bg) !important;
    border-radius: 0 0 var(--#{$prefix}accordion-inner-border-radius) var(--#{$prefix}accordion-inner-border-radius);
    border-top: none !important;
    border-left: solid;
    border-right: solid;
    border-bottom: solid;
    border-color: var(--#{$prefix}border-color);
}

.nav-callout, .pagination {
    --bs-border-radius: #{$theme-border-radius};
}

.nav-callout .tab-content {
    border-radius: #{$theme-border-radius};
}

@if $enable-dark-mode {
    @include color-mode(dark) {
        .nav-callout .accordion-button[aria-expanded="true"] {
            background-image: linear-gradient(to top right, shade-color($primary, 70%) 50%, transparent 0);
        }

        .nav-callout .accordion-collapse {
            background-color: shade-color($primary, 70%) !important;
        }
    }
}
```

## Arguments

The shortcode supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `align` | select |  | `start` | Horizontal alignment of the nav controls. Ignored when vertical is set. Supported values: [`start`, `center`, `end`]. |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `controls-placement` | select |  | `top` | Position of the nav controls relative to the content panes ("top" or "bottom"). Ignored when vertical is set. Supported values: [`top`, `bottom`]. |
| `id` | string |  |  | Unique identifier of the current element. |
| `responsive` | bool |  | `true` | Flag indicating if the element should be responsive. |
| `tab-type` | select |  |  | Type of the tab group. Supported values: [`tabs`, `pills`, `underline`, `callout`, `buttons`]. |
| `vertical` | bool |  |  | Flag to show vertical tabs instead of horizontal tabs. |
| `word-wrap` | bool |  |  | Flag to enable word wrapping of tab titles. |

In addition, the following arguments are passed to the individual navigation items.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `disabled` | bool |  |  | Flag to indicate the item should be in a disabled state. |
| `fade` | bool |  |  | Flag to make the tab pane fade in. |
| `icon` | string |  |  | Icon to display in the tab button. When set without a title, renders an icon-only button; title is then used as aria-label and tooltip. |
| `show` | bool |  |  | Flag to indicate an item should be shown. For elements with multiple items, only one item can be shown at a time. |
| `title` | string |  |  | Title of the element. If the element references a (local) page, the title overrides the referenced page's title. |

Add an inner `nav-item` element for each item of the tab group. The `nav-item` element supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `disabled` | bool |  |  | Flag to indicate the item should be in a disabled state. |
| `fade` | bool |  |  | Flag to make the tab pane fade in. |
| `icon` | string |  |  | Icon to display in the tab button. When set without a title, renders an icon-only button; title is then used as aria-label and tooltip. |
| `show` | bool |  |  | Flag to indicate an item should be shown. For elements with multiple items, only one item can be shown at a time. |
| `title` | string |  |  | Title of the element. If the element references a (local) page, the title overrides the referenced page's title. |