# Nav Item

## Usage

`NavItem` is one row in a sidebar, top bar, or menu. It renders a link when `href` is set, and a button when it is disabled or has no address. Pass a CSS icon class through `iconClass`, or use the `icon` slot. `NavIcon`, exported from the same entry, draws the round emphasis badge.

The link root defaults to `a`. Pass `RouterLink` as `as` and the item sets both `href` and `to`.

```vue
<script setup lang="ts">
import { NavItem } from '@astryx-vue/core/NavItem'
</script>

<template>
  <NavItem href="/home" icon-class="i-carbon-home" is-selected label="Home" />
</template>
```

## Best practices

| Guidance | Practice |
| --- | --- |
| Do | Set `isSelected` for the current page. The item writes `aria-current="page"`. |
| Do | Turn on `isIconOnly` when the label should stay available to assistive tech only. |
| Avoid | Do not ship a built-in icon component. Icons stay as a class or a slot. |

## Examples

### Basic

Round icon containers for a navigation header. Search and calendar sit side by side.

```vue
<script setup lang="ts">
import { NavIcon } from '@astryx-vue/core/NavItem'
import { HStack } from '@astryx-vue/core/Stack'
</script>

<template>
  <HStack align="center" :gap="4">
    <NavIcon icon-class="i-carbon-search" />
    <NavIcon icon-class="i-carbon-calendar" />
  </HStack>
</template>
```

## NavItem Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | - | Visible text. Becomes the accessible name in icon-only mode. |
| `href` | `string` | - | Renders a link when set and the item is not disabled. |
| `as` | `NavLinkComponent` | `'a'` | Link root, for example `RouterLink`. |
| `target` | `string` | - | Link target. `_blank` also adds `noopener noreferrer`. |
| `rel` | `string` | - | Link rel. |
| `isSelected` | `boolean` | `false` | Current page. Sets `aria-current="page"`. |
| `isDisabled` | `boolean` | `false` | Renders a button that is removed from tab order. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Height and padding. |
| `iconClass` | `string` | - | CSS icon class, such as `i-carbon-home`. |
| `selectedIconClass` | `string` | - | Replaces `iconClass` while selected. |
| `isIconOnly` | `boolean` | `false` | Shows the icon only. The label stays for assistive tech. |
| `block` | `boolean` | `false` | Stretches to the row width. |
| `plain` | `boolean` | `false` | Drops the item chrome so a parent can paint it. |
| `expanded` | `boolean` | - | Whether a nested group is open. Omitted when unset. |
| `controls` | `string` | - | Id written to `aria-controls`. |
| `hasPopup` | `string` | - | Popup type written to `aria-haspopup`. |

## NavItem events

| Name | Description |
| --- | --- |
| `click` | Fired on click. A disabled item prevents the default action first. |

## NavItem slots

| Name | Description |
| --- | --- |
| `default` | Replaces the visible label. |
| `icon` | Icon content. Used ahead of the glyph from `iconClass`. |
| `selectedIcon` | Icon shown while selected. |
| `end` | Trailing content, such as a chevron or count. |

## NavIcon Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `iconClass` | `string` | - | CSS icon class drawn on the round badge. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Badge diameter. |
| `label` | `string` | - | Accessible name. Without it the badge is hidden from assistive tech. |