# Nav Icon

## Usage

`NavIcon` is a circular icon container with an accent-colored background. Use it in navigation headers such as `TopNavHeading` and `PageNavHeader` to visually identify a section or application.

```ts
import { NavIcon } from '@astryx-vue/core/NavItem'
```

Pass a CSS icon class through `iconClass`, or put the icon element itself in the default slot.

### Anatomy

- **Container**: Circular painted container for the supplied icon.
- **Icon**: Caller-supplied visual content rendered inside the container.

## Best practices

| Guidance | Practice |
| --- | --- |
| Do | Use in navigation headers to provide a recognizable visual anchor for the section. |
| Do | Pass an `Icon` or similarly sized icon component to ensure proper proportions. |
| Don't | Use `NavIcon` for interactive purposes; it is a display-only container, not a button. |

## Examples

Common configurations, variations, and states.

### Basic

Circular icon containers wrapping semantic icons. Use as logos or accent icons in navigation headers such as TopNavHeading.

```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>
```

## NavIcon Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `iconClass` | `string` | — | CSS icon class drawn on the round badge, such as `i-carbon-search`. Without it the default slot is rendered. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Diameter of the badge. |
| `label` | `string` | — | Accessible name. With a label the badge is an image for assistive tech; without one it is hidden, which is right when the text beside it already says what it is. |

## Slots

- `default`: the icon content, used when `iconClass` is not set. Put an `Icon` or any element of the same size here.

The badge is display-only: it is a `span`, never a button or a link, so do not hang a click handler on it. Reach for `IconButton` or `NavItem` when the thing has to be pressable.