# Tabs

## Overview

A content switcher that organizes related views under labelled tab triggers. One tab is active at a time. Used for multi-view dashboards, analytics pages, settings sections, and any context where content is segmented but logically related.

---

## When to Use

- Switching between related views on the same page (e.g., "Overview", "Settings", "History")
- Analytics dashboards with multiple metric categories
- Settings pages with distinct sections (General, Security, Notifications)

## When NOT to Use

- Navigating between separate pages — use `<Sidebar>` or `<NavigationMenu>` instead.
- Showing/hiding a single section — use `<Collapsible>` or `<Accordion>`.

---

## Anatomy

```
<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content for tab 1</TabsContent>
  <TabsContent value="tab2">Content for tab 2</TabsContent>
</Tabs>
```

---

## Props

### Tabs

| Prop            | Type                         | Default        | Description                       |
| --------------- | ---------------------------- | -------------- | --------------------------------- |
| `defaultValue`  | `string`                     | —              | Initial active tab (uncontrolled) |
| `value`         | `string`                     | —              | Controlled active tab             |
| `onValueChange` | `(value: string) => void`    | —              | Change handler                    |
| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation                |

### TabsTrigger

| Prop       | Type      | Required | Description                                      |
| ---------- | --------- | -------- | ------------------------------------------------ |
| `value`    | `string`  | **Yes**  | Must match the corresponding `TabsContent` value |
| `disabled` | `boolean` | No       | Disables this tab                                |

### TabsContent

| Prop    | Type     | Required | Description                                      |
| ------- | -------- | -------- | ------------------------------------------------ |
| `value` | `string` | **Yes**  | Must match the corresponding `TabsTrigger` value |

---

## Examples

### Analytics Tabs

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from 'xertica-ui/ui';

<Tabs defaultValue="general">
  <TabsList>
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="performance">Performance</TabsTrigger>
    <TabsTrigger value="reports">Reports</TabsTrigger>
  </TabsList>
  <TabsContent value="general" className="mt-6">
    {/* General content */}
  </TabsContent>
  <TabsContent value="performance" className="mt-6">
    {/* Performance charts */}
  </TabsContent>
  <TabsContent value="reports" className="mt-6">
    {/* Reports table */}
  </TabsContent>
</Tabs>;
```

### Controlled

```tsx
const [tab, setTab] = useState('general');

<Tabs value={tab} onValueChange={setTab}>
  <TabsList>
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="security">Security</TabsTrigger>
  </TabsList>
  <TabsContent value="general">...</TabsContent>
  <TabsContent value="security">...</TabsContent>
</Tabs>;
```

---

## AI Rules

- Every `TabsTrigger` must have a `value` that exactly matches a `TabsContent` `value`.
- `TabsContent` should add `className="mt-6"` or `className="mt-4"` for spacing between the tabs and content.
- `TabsList` should not have its width constrained to auto — let it fill the available horizontal space unless the design requires otherwise.
- Do not use Tabs for page-level navigation — use router and `Sidebar` for that.

---

## Related Components

- [`Accordion`](./accordion.md) — For expandable sections instead of tabs
- [`Card`](./card.md) — Tabs content often lives inside a Card