# Core/TabNav - Usage

TabNav provides a horizontal or vertical navigation styled as tabs. Tab items are links that redirect to URLs. With `subItems`, horizontal tabs open a dropdown menu; vertical tabs use an inline indented list (Tab Nav | Vertical in Figma).

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `never` | No | `--` | Use `FORCE__className` instead. |
| `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
| `activeKey` | `string` | No | `--` | Key of the currently active tab (for visual styling). Typically derived from the current URL. |
| `onTabPress` | `(key: string) => void` | No | `--` | Callback when a tab link is pressed (before navigation). |
| `onTabClick` | `(key: string, event: React.MouseEvent) => void` | No | `--` | Callback when a tab link is clicked (before navigation).<br>@deprecated Use `onTabPress` instead. |
| `items` | `TabNavItemType[]` | Yes | `--` | Tab items configuration. |
| `tabPlacement` | `(typeof tabNavPlacements)[number]` | No | 'horizontal' | Orientation of the tab bar: horizontal (bottom) or vertical (left).<br>@default 'horizontal' |
| `centered` | `boolean` | No | false | Whether to center the tabs.<br>@default false |
| `tabBarExtraSlot` | `React.ReactNode` | No | `--` | Slot for extra content in the tab bar (e.g. right side). |
| `wrap` | `boolean` | No | true | Whether tab items can wrap to multiple lines.<br>@default true |
| `aria-label` | `string` | No | 'Navigation' | `--` |

## Usage

```tsx
import { RouterProvider, TabNav } from '@capra/core';

// Basic usage - tab items are links that redirect to URLs
<TabNav
  activeKey={currentPath}
  items={[
    { key: '1', name: 'Tab 1', href: '/tab1' },
    { key: '2', name: 'Tab 2', href: '/tab2' },
  ]}
/>

// Optional `name` (visible) + `aria-label` on the item when the accessible name differs
<TabNav
  activeKey="overview"
  items={[
    { key: 'overview', name: 'Overview', 'aria-label': 'Tab 1, 1 of 3, selected', href: '/overview' },
  ]}
/>

// With icons and disabled tab
<TabNav
  activeKey="1"
  items={[
    { key: '1', name: 'Search', icon: <SearchOutlined size="sm" />, href: '/search' },
    { key: '2', name: 'Disabled', disabled: true, href: '/disabled' },
  ]}
/>

// With subnav dropdown (tabs with subItems show a chevron and open a menu on click)
<TabNav
  activeKey="overview::summary"
  items={[
    {
      key: 'overview',
      name: 'Overview',
      subItems: [
        { key: 'summary', name: 'Summary', href: '/overview/summary' },
        { key: 'details', name: 'Details', href: '/overview/details' },
      ],
    },
    { key: 'settings', name: 'Settings', href: '/settings' },
  ]}
/>

// With client-side routing
<RouterProvider navigate={navigate}>
  <TabNav
    activeKey={currentPath}
    items={[
      { key: 'overview', name: 'Overview', href: '/overview' },
      {
        key: 'settings',
        name: 'Settings',
        subItems: [{ key: 'profile', name: 'Profile', href: '/settings/profile' }],
      },
    ]}
  />
</RouterProvider>
```

When the app provides `RouterProvider`, `TabNav` passes `href` and the rest of `RoutedLinkProps` through to navigable tabs and sub-items so routing stays client-side.