# Top Nav Item

## Usage

`TopNavItem` is a navigation link item for the `start` slot or the default slot of `TopNav`: it renders as an anchor with hover and selected states.

With `href` set, the item is a link. Without an address, or with `isDisabled`, it renders as a button instead, so it cannot navigate.

```ts
import { TopNavItem } from '@astryx-vue/core/TopNav'
```

## Examples

Common configurations, variations, and states.

### Basic

Navigation links inside a TopNav with one item marked as selected. Use for top-level pages of an application.

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

<template>
  <TopNav label="Main navigation">
    <template #heading>
      <TopNavHeading heading="App" />
    </template>
    <TopNavItem href="#" is-selected label="Dashboard" />
    <TopNavItem href="#" label="Projects" />
    <TopNavItem href="#" label="Reports" />
  </TopNav>
</template>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Accessible label for the nav item. Rendered as visible text by default. When `isIconOnly` is true, it becomes the `aria-label` instead. Required. |
| `href` | `string` | — | Navigation target URL. |
| `as` | `NavLinkComponent` | `'a'` | Custom link root component, such as `RouterLink`. It receives the address as `to` as well. Used only when there is an address. |
| `target` | `string` | — | Link `target`. A new-window target also adds `noopener noreferrer`. |
| `rel` | `string` | — | Link `rel`. Merged with the `noopener noreferrer` that a new-window target adds. |
| `iconClass` | `string` | — | Icon shown before the label, given as a CSS icon class such as `i-carbon-home`. |
| `isSelected` | `boolean` | `false` | Whether this nav item is currently selected. Sets `aria-current="page"` and applies highlighted styles. |
| `isDisabled` | `boolean` | `false` | Whether the nav item is disabled. Sets `aria-disabled`, drops href/target so the item cannot navigate, and prevents interaction. |
| `isIconOnly` | `boolean` | `false` | Renders the item as a square icon-only element. When true, `label` becomes the `aria-label` and the visible text is hidden. Inside the mobile drawer the label is shown again. |
| `size` | `NavItemSize` | `'md'` | Height and horizontal padding of the item: `'sm'` is 28px, `'md'` 32px, `'lg'` 36px. |

## Events

- `click(event: MouseEvent)`: fires when the item is clicked. A disabled item blocks the default action and emits nothing.