From 0afcb06529c4c93aeb357d9554b6b16807bbe5ee Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 5 May 2026 11:38:35 -0400
Subject: [PATCH] feat(headless): add Tabs primitive

---
 packages/headless/package.json                |   4 +
 .../headless/src/primitives/tabs/README.md    | 199 ++++++++
 .../headless/src/primitives/tabs/index.ts     |   9 +
 .../src/primitives/tabs/tabs.test.tsx         | 456 ++++++++++++++++++
 .../headless/src/primitives/tabs/tabs.tsx     | 448 +++++++++++++++++
 packages/headless/vite.config.ts              |   1 +
 6 files changed, 1117 insertions(+)
 create mode 100644 packages/headless/src/primitives/tabs/README.md
 create mode 100644 packages/headless/src/primitives/tabs/index.ts
 create mode 100644 packages/headless/src/primitives/tabs/tabs.test.tsx
 create mode 100644 packages/headless/src/primitives/tabs/tabs.tsx

diff --git a/packages/headless/package.json b/packages/headless/package.json
index 67e04bed3e3..8080f593513 100644
--- a/packages/headless/package.json
+++ b/packages/headless/package.json
@@ -8,6 +8,10 @@
       "import": "./dist/primitives/accordion/index.js",
       "types": "./dist/primitives/accordion/index.d.ts"
     },
+    "./tabs": {
+      "import": "./dist/primitives/tabs/index.js",
+      "types": "./dist/primitives/tabs/index.d.ts"
+    },
     "./dialog": {
       "import": "./dist/primitives/dialog/index.js",
       "types": "./dist/primitives/dialog/index.d.ts"
diff --git a/packages/headless/src/primitives/tabs/README.md b/packages/headless/src/primitives/tabs/README.md
new file mode 100644
index 00000000000..ab3761db82d
--- /dev/null
+++ b/packages/headless/src/primitives/tabs/README.md
@@ -0,0 +1,199 @@
+# Tabs
+
+A tabbed interface with automatic or manual activation, keyboard navigation, and an animated indicator. Panels are shown/hidden via the HTML `hidden` attribute (not unmounted).
+
+## When to Use
+
+- Switching between views or content sections within the same page area.
+- When you need accessible tab navigation with `role="tablist"` / `role="tab"` / `role="tabpanel"`.
+- Prefer Tabs over Accordion when content sections are mutually exclusive and should feel like parallel views.
+
+## Usage
+
+```tsx
+import { Tabs } from '@/primitives/tabs';
+
+<Tabs defaultValue='tab1'>
+  <Tabs.List>
+    <Tabs.Tab value='tab1'>Account</Tabs.Tab>
+    <Tabs.Tab value='tab2'>Security</Tabs.Tab>
+    <Tabs.Tab value='tab3'>Notifications</Tabs.Tab>
+    <Tabs.Indicator />
+  </Tabs.List>
+  <Tabs.Panel value='tab1'>Account settings content</Tabs.Panel>
+  <Tabs.Panel value='tab2'>Security settings content</Tabs.Panel>
+  <Tabs.Panel value='tab3'>Notification preferences content</Tabs.Panel>
+</Tabs>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('tab1');
+
+<Tabs
+  value={value}
+  onValueChange={setValue}
+>
+  {/* ... */}
+</Tabs>;
+```
+
+### Manual Activation
+
+By default, arrowing to a tab immediately activates it. Use `activationMode="manual"` to require Enter/Space:
+
+```tsx
+<Tabs activationMode='manual'>{/* Arrow keys move focus, Enter/Space activates */}</Tabs>
+```
+
+### Vertical Orientation
+
+```tsx
+<Tabs orientation='vertical'>{/* Arrow Up/Down navigates instead of Left/Right */}</Tabs>
+```
+
+## Parts
+
+| Part             | Default Element | Description                                        |
+| ---------------- | --------------- | -------------------------------------------------- |
+| `Tabs`           | —               | Root context provider                              |
+| `Tabs.List`      | `<div>`         | Container for tabs (`role="tablist"`)              |
+| `Tabs.Tab`       | `<button>`      | A tab trigger inside `Tabs.List` (`role="tab"`)    |
+| `Tabs.Trigger`   | `<button>`      | Standalone tab trigger for use outside `Tabs.List` |
+| `Tabs.Panel`     | `<div>`         | Content panel (`role="tabpanel"`)                  |
+| `Tabs.Indicator` | `<span>`        | Animated indicator tracking the active tab         |
+
+## Props
+
+### `Tabs` (root)
+
+| Prop             | Type                         | Default        | Description                               |
+| ---------------- | ---------------------------- | -------------- | ----------------------------------------- |
+| `value`          | `string`                     | —              | Controlled active tab                     |
+| `defaultValue`   | `string`                     | `""`           | Initial active tab (uncontrolled)         |
+| `onValueChange`  | `(value: string) => void`    | —              | Called when active tab changes            |
+| `orientation`    | `"horizontal" \| "vertical"` | `"horizontal"` | Arrow key direction                       |
+| `activationMode` | `"automatic" \| "manual"`    | `"automatic"`  | Whether focus activates a tab immediately |
+
+### `Tabs.Tab`
+
+| Prop       | Type      | Default      | Description                                                |
+| ---------- | --------- | ------------ | ---------------------------------------------------------- |
+| `value`    | `string`  | **required** | Unique tab identifier, must match a Panel's `value`        |
+| `disabled` | `boolean` | —            | Disables the tab (uses `aria-disabled`, remains focusable) |
+
+### `Tabs.Trigger`
+
+A standalone tab button for use outside `Tabs.List`. Unlike `Tabs.Tab`, it does not participate in roving tabindex keyboard navigation — it's a plain button with `onClick`.
+
+| Prop       | Type      | Default      | Description                                  |
+| ---------- | --------- | ------------ | -------------------------------------------- |
+| `value`    | `string`  | **required** | Tab identifier, must match a Panel's `value` |
+| `disabled` | `boolean` | —            | Disables the trigger                         |
+
+### `Tabs.Panel`
+
+| Prop               | Type      | Default      | Description                                                         |
+| ------------------ | --------- | ------------ | ------------------------------------------------------------------- |
+| `value`            | `string`  | **required** | Must match a Tab's `value`                                          |
+| `shouldForceMount` | `boolean` | —            | When true, keeps the panel in layout flow instead of using `hidden` |
+
+### `Tabs.List`, `Tabs.Indicator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+## Keyboard Navigation
+
+| Key               | Action (horizontal)        | Action (vertical)          |
+| ----------------- | -------------------------- | -------------------------- |
+| `ArrowRight`      | Next tab                   | —                          |
+| `ArrowLeft`       | Previous tab               | —                          |
+| `ArrowDown`       | —                          | Next tab                   |
+| `ArrowUp`         | —                          | Previous tab               |
+| `Enter` / `Space` | Activate tab (manual mode) | Activate tab (manual mode) |
+
+## Data Attributes
+
+| Attribute                | Applies To   | Description                                           |
+| ------------------------ | ------------ | ----------------------------------------------------- |
+| `data-cl-slot`           | All parts    | Part identifier (e.g. `"tabs-tab"`, `"tabs-trigger"`) |
+| `data-cl-selected`       | Tab, Trigger | Active tab                                            |
+| `data-cl-disabled`       | Tab, Trigger | Disabled tab                                          |
+| `data-cl-hidden`         | Panel        | Inactive panel                                        |
+| `data-cl-open`           | Panel        | Selected panel (when `shouldForceMount`)              |
+| `data-cl-closed`         | Panel        | Deselected panel (when `shouldForceMount`)            |
+| `data-cl-starting-style` | Panel        | Enter animation frame (when `shouldForceMount`)       |
+| `data-cl-ending-style`   | Panel        | Exit animation frame (when `shouldForceMount`)        |
+
+## CSS Variables
+
+### Indicator
+
+`Tabs.Indicator` exposes CSS custom properties for positioning and sizing:
+
+| CSS Variable      | Description                        |
+| ----------------- | ---------------------------------- |
+| `--cl-tab-left`   | Left offset of the active tab (px) |
+| `--cl-tab-width`  | Width of the active tab (px)       |
+| `--cl-tab-top`    | Top offset of the active tab (px)  |
+| `--cl-tab-height` | Height of the active tab (px)      |
+
+Use these to animate the indicator:
+
+```css
+[data-cl-slot='tabs-indicator'] {
+  position: absolute;
+  left: var(--cl-tab-left);
+  width: var(--cl-tab-width);
+  transition:
+    left 200ms ease,
+    width 200ms ease;
+}
+```
+
+The initial render suppresses the transition to prevent the indicator from animating from `0,0`.
+
+### Panel (with `shouldForceMount`)
+
+When `shouldForceMount` is set, panels expose a direction variable for directional animations:
+
+| CSS Variable                    | Description                                                    |
+| ------------------------------- | -------------------------------------------------------------- |
+| `--cl-tab-transition-direction` | `"1"` when navigating forward, `"-1"` when navigating backward |
+
+Use this to drive directional slide animations:
+
+```css
+[data-cl-slot='tabs-panel'] {
+  --_direction: var(--cl-tab-transition-direction, 1);
+  transition:
+    opacity 200ms,
+    translate 200ms;
+}
+[data-cl-slot='tabs-panel'][data-cl-starting-style],
+[data-cl-slot='tabs-panel'][data-cl-ending-style] {
+  opacity: 0;
+}
+[data-cl-slot='tabs-panel'][data-cl-starting-style] {
+  translate: calc(var(--_direction) * 8px) 0;
+}
+[data-cl-slot='tabs-panel'][data-cl-ending-style] {
+  translate: calc(var(--_direction) * -8px) 0;
+}
+```
+
+## Important Notes
+
+- **`Tabs.List` must have `position: relative`** in your CSS for the indicator to position correctly.
+- **Panels use the `hidden` attribute** by default — they stay in the DOM but are hidden when inactive. This preserves state in inactive panels.
+- **`shouldForceMount` panels** stay in layout flow with `inert` on inactive panels. This enables CSS enter/exit animations between tabs. The initially-selected panel appears instantly (no enter animation on page load).
+- **`Tabs.Trigger` vs `Tabs.Tab`**: Use `Tabs.Tab` inside `Tabs.List` for keyboard-navigable tabs with roving tabindex. Use `Tabs.Trigger` for standalone tab buttons placed anywhere in the tree (e.g., in a sidebar).
+- **Disabled tabs use `aria-disabled`**, not the native `disabled` attribute, keeping them focusable for keyboard users.
+- **Indicator is `aria-hidden`** — it's purely decorative.
+
+## ARIA
+
+- List: `role="tablist"`
+- Tab: `role="tab"`, `aria-selected`, `aria-controls` (pointing to its panel), `aria-disabled`
+- Panel: `role="tabpanel"`, `aria-labelledby` (pointing to its tab), `tabIndex={0}`
diff --git a/packages/headless/src/primitives/tabs/index.ts b/packages/headless/src/primitives/tabs/index.ts
new file mode 100644
index 00000000000..7679cea7993
--- /dev/null
+++ b/packages/headless/src/primitives/tabs/index.ts
@@ -0,0 +1,9 @@
+export type {
+  TabsIndicatorProps,
+  TabsListProps,
+  TabsPanelProps,
+  TabsProps,
+  TabsTabProps,
+  TabsTriggerProps,
+} from './tabs';
+export { Tabs } from './tabs';
diff --git a/packages/headless/src/primitives/tabs/tabs.test.tsx b/packages/headless/src/primitives/tabs/tabs.test.tsx
new file mode 100644
index 00000000000..7da4cefc511
--- /dev/null
+++ b/packages/headless/src/primitives/tabs/tabs.test.tsx
@@ -0,0 +1,456 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Tabs } from './tabs';
+
+afterEach(() => cleanup());
+
+function renderTabs(props: Partial<React.ComponentProps<typeof Tabs>> = {}) {
+  return render(
+    <Tabs
+      defaultValue='tab1'
+      {...props}
+    >
+      <Tabs.List>
+        <Tabs.Tab value='tab1'>Account</Tabs.Tab>
+        <Tabs.Tab value='tab2'>Settings</Tabs.Tab>
+        <Tabs.Tab value='tab3'>Billing</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
+      <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
+      <Tabs.Panel value='tab3'>Billing content</Tabs.Panel>
+    </Tabs>,
+  );
+}
+
+describe('Tabs', () => {
+  describe('slot attributes', () => {
+    it('renders list with data-cl-slot', () => {
+      renderTabs();
+      expect(document.querySelector('[data-cl-slot="tabs-list"]')).toBeInTheDocument();
+    });
+
+    it('renders tabs with data-cl-slot', () => {
+      renderTabs();
+      const tabs = document.querySelectorAll('[data-cl-slot="tabs-tab"]');
+      expect(tabs).toHaveLength(3);
+    });
+
+    it('renders panels with data-cl-slot', () => {
+      renderTabs();
+      const panels = document.querySelectorAll('[data-cl-slot="tabs-panel"]');
+      expect(panels).toHaveLength(3);
+    });
+  });
+
+  describe('ARIA attributes', () => {
+    it('list has role=tablist', () => {
+      renderTabs();
+      expect(screen.getByRole('tablist')).toBeInTheDocument();
+    });
+
+    it('list has aria-orientation', () => {
+      renderTabs();
+      expect(screen.getByRole('tablist')).toHaveAttribute('aria-orientation', 'horizontal');
+    });
+
+    it('vertical orientation sets aria-orientation', () => {
+      renderTabs({ orientation: 'vertical' });
+      expect(screen.getByRole('tablist')).toHaveAttribute('aria-orientation', 'vertical');
+    });
+
+    it('tabs have role=tab', () => {
+      renderTabs();
+      expect(screen.getAllByRole('tab')).toHaveLength(3);
+    });
+
+    it('selected tab has aria-selected=true', () => {
+      renderTabs();
+      expect(screen.getByText('Account')).toHaveAttribute('aria-selected', 'true');
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'false');
+    });
+
+    it('panels have role=tabpanel', () => {
+      renderTabs();
+      // Only the selected panel is visible
+      expect(screen.getByRole('tabpanel')).toBeInTheDocument();
+    });
+
+    it('tab has aria-controls linking to panel', () => {
+      renderTabs();
+      const tab = screen.getByText('Account');
+      const panelId = tab.getAttribute('aria-controls');
+      expect(panelId).toBeTruthy();
+      expect(document.getElementById(panelId!)).toHaveTextContent('Account content');
+    });
+
+    it('panel has aria-labelledby linking to tab', () => {
+      renderTabs();
+      const panel = screen.getByRole('tabpanel');
+      const tabId = panel.getAttribute('aria-labelledby');
+      expect(tabId).toBeTruthy();
+      expect(document.getElementById(tabId!)).toHaveTextContent('Account');
+    });
+  });
+
+  describe('selection', () => {
+    it('shows selected panel content', () => {
+      renderTabs();
+      expect(screen.getByText('Account content')).toBeVisible();
+      expect(screen.getByText('Settings content')).not.toBeVisible();
+    });
+
+    it('selects tab on click', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Settings'));
+
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'true');
+      expect(screen.getByText('Settings content')).toBeVisible();
+    });
+
+    it('marks selected tab with data-cl-selected', () => {
+      renderTabs();
+      expect(screen.getByText('Account')).toHaveAttribute('data-cl-selected', '');
+      expect(screen.getByText('Settings').hasAttribute('data-cl-selected')).toBe(false);
+    });
+
+    it('calls onValueChange on selection', async () => {
+      const onValueChange = vi.fn();
+      const user = userEvent.setup();
+      renderTabs({ onValueChange });
+
+      await user.click(screen.getByText('Settings'));
+
+      expect(onValueChange).toHaveBeenCalledWith('tab2');
+    });
+  });
+
+  describe('controlled value', () => {
+    it('respects controlled value prop', () => {
+      renderTabs({ value: 'tab2' });
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'true');
+      expect(screen.getByText('Settings content')).toBeVisible();
+    });
+
+    it('does not change internally when controlled', async () => {
+      const user = userEvent.setup();
+      renderTabs({ value: 'tab1' });
+
+      await user.click(screen.getByText('Settings'));
+
+      // Still on tab1 since controlled
+      expect(screen.getByText('Account')).toHaveAttribute('aria-selected', 'true');
+    });
+  });
+
+  describe('keyboard navigation — automatic activation', () => {
+    it('moves focus with ArrowRight', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowRight}');
+
+      expect(document.activeElement).toBe(screen.getByText('Settings'));
+      // Automatic mode: focus triggers selection
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('moves focus with ArrowLeft', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Settings'));
+      await user.keyboard('{ArrowLeft}');
+
+      expect(document.activeElement).toBe(screen.getByText('Account'));
+    });
+
+    it('wraps around at the end (loop)', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Billing'));
+      await user.keyboard('{ArrowRight}');
+
+      expect(document.activeElement).toBe(screen.getByText('Account'));
+    });
+
+    it('wraps around at the start', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowLeft}');
+
+      expect(document.activeElement).toBe(screen.getByText('Billing'));
+    });
+
+    it('uses ArrowDown/ArrowUp for vertical orientation', async () => {
+      const user = userEvent.setup();
+      renderTabs({ orientation: 'vertical' });
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowDown}');
+
+      expect(document.activeElement).toBe(screen.getByText('Settings'));
+    });
+
+    it('moves focus to first tab with Home', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Billing'));
+      await user.keyboard('{Home}');
+
+      expect(document.activeElement).toBe(screen.getByText('Account'));
+    });
+
+    it('moves focus to last tab with End', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{End}');
+
+      expect(document.activeElement).toBe(screen.getByText('Billing'));
+    });
+
+    it('Tab key moves focus from tab to panel', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Account'));
+      await user.tab();
+
+      const panel = screen.getByRole('tabpanel');
+      expect(document.activeElement).toBe(panel);
+    });
+
+    it('Home skips disabled tabs', async () => {
+      const user = userEvent.setup();
+      render(
+        <Tabs defaultValue='tab3'>
+          <Tabs.List>
+            <Tabs.Tab
+              value='tab1'
+              disabled
+            >
+              First
+            </Tabs.Tab>
+            <Tabs.Tab value='tab2'>Second</Tabs.Tab>
+            <Tabs.Tab value='tab3'>Third</Tabs.Tab>
+          </Tabs.List>
+          <Tabs.Panel value='tab1'>Panel 1</Tabs.Panel>
+          <Tabs.Panel value='tab2'>Panel 2</Tabs.Panel>
+          <Tabs.Panel value='tab3'>Panel 3</Tabs.Panel>
+        </Tabs>,
+      );
+
+      await user.click(screen.getByText('Third'));
+      await user.keyboard('{Home}');
+
+      expect(document.activeElement).toBe(screen.getByText('Second'));
+    });
+  });
+
+  describe('keyboard navigation — manual activation', () => {
+    it('moves focus without selecting', async () => {
+      const user = userEvent.setup();
+      renderTabs({ activationMode: 'manual' });
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowRight}');
+
+      expect(document.activeElement).toBe(screen.getByText('Settings'));
+      // Manual mode: focus does NOT select
+      expect(screen.getByText('Account')).toHaveAttribute('aria-selected', 'true');
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'false');
+    });
+
+    it('selects on Enter', async () => {
+      const user = userEvent.setup();
+      renderTabs({ activationMode: 'manual' });
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowRight}{Enter}');
+
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('selects on Space', async () => {
+      const user = userEvent.setup();
+      renderTabs({ activationMode: 'manual' });
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowRight} ');
+
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'true');
+    });
+  });
+
+  describe('disabled tab', () => {
+    function renderWithDisabled() {
+      return render(
+        <Tabs defaultValue='tab1'>
+          <Tabs.List>
+            <Tabs.Tab value='tab1'>Account</Tabs.Tab>
+            <Tabs.Tab
+              value='tab2'
+              disabled
+            >
+              Settings
+            </Tabs.Tab>
+            <Tabs.Tab value='tab3'>Billing</Tabs.Tab>
+          </Tabs.List>
+          <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
+          <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
+          <Tabs.Panel value='tab3'>Billing content</Tabs.Panel>
+        </Tabs>,
+      );
+    }
+
+    it('disabled tab has data-cl-disabled', () => {
+      renderWithDisabled();
+      expect(screen.getByText('Settings')).toHaveAttribute('data-cl-disabled', '');
+    });
+
+    it('disabled tab has aria-disabled', () => {
+      renderWithDisabled();
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('skips disabled tab during keyboard navigation', async () => {
+      const user = userEvent.setup();
+      renderWithDisabled();
+
+      await user.click(screen.getByText('Account'));
+      await user.keyboard('{ArrowRight}');
+
+      // Should skip Settings (disabled) and land on Billing
+      expect(document.activeElement).toBe(screen.getByText('Billing'));
+    });
+
+    it('does not select disabled tab on click', async () => {
+      const user = userEvent.setup();
+      renderWithDisabled();
+
+      await user.click(screen.getByText('Settings'));
+
+      expect(screen.getByText('Account')).toHaveAttribute('aria-selected', 'true');
+    });
+  });
+
+  describe('Tabs.Indicator', () => {
+    function renderWithIndicator() {
+      return render(
+        <Tabs defaultValue='tab1'>
+          <Tabs.List style={{ position: 'relative' }}>
+            <Tabs.Tab value='tab1'>Account</Tabs.Tab>
+            <Tabs.Tab value='tab2'>Settings</Tabs.Tab>
+            <Tabs.Indicator data-testid='indicator' />
+          </Tabs.List>
+          <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
+          <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
+        </Tabs>,
+      );
+    }
+
+    it('renders with data-cl-slot', () => {
+      renderWithIndicator();
+      expect(document.querySelector('[data-cl-slot="tabs-indicator"]')).toBeInTheDocument();
+    });
+
+    it('has position absolute', () => {
+      renderWithIndicator();
+      const indicator = screen.getByTestId('indicator');
+      expect(indicator.style.position).toBe('absolute');
+    });
+
+    it('has aria-hidden', () => {
+      renderWithIndicator();
+      const indicator = screen.getByTestId('indicator');
+      expect(indicator).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('sets --cl-tab-width and --cl-tab-left CSS vars', () => {
+      renderWithIndicator();
+      const indicator = screen.getByTestId('indicator');
+      // In a real browser, getBoundingClientRect returns actual measurements
+      expect(indicator.style.getPropertyValue('--cl-tab-width')).toBeTruthy();
+      expect(indicator.style.getPropertyValue('--cl-tab-left')).toBeTruthy();
+    });
+
+    it('updates position when tab changes', async () => {
+      const user = userEvent.setup();
+      renderWithIndicator();
+
+      const indicator = screen.getByTestId('indicator');
+      const initialLeft = indicator.style.left;
+
+      await user.click(screen.getByText('Settings'));
+
+      // Verify the effect ran and style properties are set
+      expect(indicator.style.position).toBe('absolute');
+      expect(indicator.style.getPropertyValue('--cl-tab-width')).toBeDefined();
+    });
+
+    it('skips transition on initial render', () => {
+      renderWithIndicator();
+      const indicator = screen.getByTestId('indicator');
+      expect(indicator.style.transition).toBe('none');
+    });
+  });
+
+  describe('panel visibility', () => {
+    it('hides non-selected panels with hidden attribute', () => {
+      renderTabs();
+      const panels = document.querySelectorAll('[data-cl-slot="tabs-panel"]');
+      const visible = Array.from(panels).filter(p => !p.hasAttribute('hidden'));
+      const hidden = Array.from(panels).filter(p => p.hasAttribute('hidden'));
+
+      expect(visible).toHaveLength(1);
+      expect(hidden).toHaveLength(2);
+    });
+
+    it('non-selected panels have data-cl-hidden', () => {
+      renderTabs();
+      const panels = document.querySelectorAll('[data-cl-slot="tabs-panel"][data-cl-hidden]');
+      expect(panels).toHaveLength(2);
+    });
+  });
+
+  describe('roving tabindex', () => {
+    it('selected tab has tabIndex=0, others have tabIndex=-1', () => {
+      renderTabs();
+      expect(screen.getByText('Account')).toHaveAttribute('tabindex', '0');
+      expect(screen.getByText('Settings')).toHaveAttribute('tabindex', '-1');
+      expect(screen.getByText('Billing')).toHaveAttribute('tabindex', '-1');
+    });
+
+    it('tabIndex updates when selection changes', async () => {
+      const user = userEvent.setup();
+      renderTabs();
+
+      await user.click(screen.getByText('Settings'));
+
+      expect(screen.getByText('Account')).toHaveAttribute('tabindex', '-1');
+      expect(screen.getByText('Settings')).toHaveAttribute('tabindex', '0');
+    });
+  });
+
+  describe('accessibility (axe)', () => {
+    it('has no violations', async () => {
+      const { container } = renderTabs();
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('has no violations with vertical orientation', async () => {
+      const { container } = renderTabs({ orientation: 'vertical' });
+      expect(await axe(container)).toHaveNoViolations();
+    });
+  });
+});
diff --git a/packages/headless/src/primitives/tabs/tabs.tsx b/packages/headless/src/primitives/tabs/tabs.tsx
new file mode 100644
index 00000000000..1312e6466db
--- /dev/null
+++ b/packages/headless/src/primitives/tabs/tabs.tsx
@@ -0,0 +1,448 @@
+'use client';
+
+import { Composite, CompositeItem } from '@floating-ui/react';
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { useTransition } from '../../hooks/use-transition';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+interface TabsContextValue {
+  value: string;
+  setValue: (value: string) => void;
+  orientation: 'horizontal' | 'vertical';
+  activationMode: 'automatic' | 'manual';
+  tabsId: string;
+  registerTab: (value: string, element: HTMLElement | null) => void;
+  getTabElement: (value: string) => HTMLElement | null;
+  listRef: React.RefObject<HTMLElement | null>;
+  direction: 1 | -1;
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+function useTabsContext() {
+  const ctx = useContext(TabsContext);
+  if (!ctx) {
+    throw new Error('Tabs compound components must be used within <Tabs>');
+  }
+  return ctx;
+}
+
+// ---------------------------------------------------------------------------
+// Tabs (root)
+// ---------------------------------------------------------------------------
+
+export interface TabsProps {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  orientation?: 'horizontal' | 'vertical';
+  activationMode?: 'automatic' | 'manual';
+  children: ReactNode;
+}
+
+function TabsRoot(props: TabsProps) {
+  const { orientation = 'horizontal', activationMode = 'automatic', children } = props;
+
+  const [value, setValueRaw] = useControllableState(props.value, props.defaultValue ?? '', props.onValueChange);
+
+  const [direction, setDirection] = useState<1 | -1>(1);
+  const tabsId = useId();
+  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
+  const tabOrderRef = useRef<string[]>([]);
+  const listRef = useRef<HTMLElement | null>(null);
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
+  const registerTab = useCallback((tabValue: string, element: HTMLElement | null) => {
+    if (element) {
+      tabElementsRef.current.set(tabValue, element);
+      if (!tabOrderRef.current.includes(tabValue)) {
+        tabOrderRef.current.push(tabValue);
+      }
+    } else {
+      tabElementsRef.current.delete(tabValue);
+    }
+  }, []);
+
+  const getTabElement = useCallback((tabValue: string) => {
+    return tabElementsRef.current.get(tabValue) ?? null;
+  }, []);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      const prevIndex = tabOrderRef.current.indexOf(valueRef.current);
+      const nextIndex = tabOrderRef.current.indexOf(newValue);
+      if (prevIndex !== -1 && nextIndex !== -1) {
+        setDirection(nextIndex > prevIndex ? 1 : -1);
+      }
+      setValueRaw(newValue);
+    },
+    [setValueRaw],
+  );
+
+  const contextValue = useMemo<TabsContextValue>(
+    () => ({
+      value,
+      setValue,
+      orientation,
+      activationMode,
+      tabsId,
+      registerTab,
+      getTabElement,
+      listRef,
+      direction,
+    }),
+    [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+  );
+
+  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;
+}
+
+// ---------------------------------------------------------------------------
+// Tabs.List
+// ---------------------------------------------------------------------------
+
+export interface TabsListProps extends ComponentProps<'div'> {}
+
+function TabsList(props: TabsListProps) {
+  const { render, children, ...otherProps } = props;
+  const { orientation, listRef } = useTabsContext();
+
+  return (
+    <Composite
+      ref={listRef}
+      orientation={orientation}
+      render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
+        const defaultProps: Record<string, unknown> = {
+          'data-cl-slot': 'tabs-list',
+          role: 'tablist' as const,
+          onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => {
+            if (event.key !== 'Home' && event.key !== 'End') return;
+            event.preventDefault();
+            const items = Array.from(event.currentTarget.querySelectorAll<HTMLElement>('[role="tab"]:not([disabled])'));
+            if (items.length === 0) return;
+            const target = event.key === 'Home' ? items[0] : items[items.length - 1];
+            target.focus();
+          },
+        };
+
+        const merged = mergeProps<'div'>(
+          defaultProps,
+          mergeProps<'div'>(otherProps, compositeProps as Record<string, unknown>),
+        );
+
+        return renderElement({
+          defaultTagName: 'div',
+          render,
+          props: merged,
+        })!;
+      }}
+    >
+      {children}
+    </Composite>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tabs.Tab
+// ---------------------------------------------------------------------------
+
+export interface TabsTabProps extends ComponentProps<'button'> {
+  value: string;
+  disabled?: boolean;
+}
+
+function TabsTab(props: TabsTabProps) {
+  const { render, value: tabValue, disabled, children, ...otherProps } = props;
+  const { value: selectedValue, setValue, activationMode, tabsId, registerTab } = useTabsContext();
+
+  const isSelected = selectedValue === tabValue;
+  const tabId = `${tabsId}-tab-${tabValue}`;
+  const panelId = `${tabsId}-panel-${tabValue}`;
+  const internalRef = useRef<HTMLButtonElement | null>(null);
+
+  useLayoutEffect(() => {
+    registerTab(tabValue, internalRef.current);
+    return () => registerTab(tabValue, null);
+  }, [tabValue, registerTab]);
+
+  const state = {
+    selected: isSelected,
+    disabled: !!disabled,
+  };
+
+  return (
+    <CompositeItem
+      ref={internalRef}
+      disabled={disabled}
+      render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
+        const defaultProps: Record<string, unknown> = {
+          'data-cl-slot': 'tabs-tab',
+          id: tabId,
+          role: 'tab' as const,
+          type: 'button' as const,
+          'aria-selected': isSelected,
+          'aria-controls': panelId,
+          'aria-disabled': disabled || undefined,
+        };
+
+        if (activationMode === 'automatic') {
+          defaultProps.onFocus = (event: React.FocusEvent<HTMLButtonElement>) => {
+            if (!disabled) setValue(tabValue);
+          };
+        } else {
+          defaultProps.onClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+            if (!disabled) setValue(tabValue);
+          };
+          defaultProps.onKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+            if (!disabled && (event.key === 'Enter' || event.key === ' ')) {
+              event.preventDefault();
+              setValue(tabValue);
+            }
+          };
+        }
+
+        // Merge: defaultProps first, then consumer props, then composite props last
+        // (composite needs to win on tabIndex, data-active, onFocus, ref)
+        const merged = mergeProps<'button'>(
+          mergeProps<'button'>(defaultProps as Record<string, unknown>, otherProps),
+          compositeProps as Record<string, unknown>,
+        );
+
+        return renderElement({
+          defaultTagName: 'button',
+          render,
+          state,
+          stateAttributesMapping: {
+            selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+            disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+          },
+          props: merged,
+        })!;
+      }}
+    >
+      {children}
+    </CompositeItem>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tabs.Panel
+// ---------------------------------------------------------------------------
+
+export interface TabsPanelProps extends ComponentProps<'div'> {
+  value: string;
+  /** When true, removes `hidden` so the panel stays in layout flow. */
+  shouldForceMount?: boolean;
+}
+
+function TabsPanel(props: TabsPanelProps) {
+  const { render, value: panelValue, shouldForceMount, ...otherProps } = props;
+  const { value: selectedValue, tabsId, direction } = useTabsContext();
+
+  const isSelected = selectedValue === panelValue;
+  const tabId = `${tabsId}-tab-${panelValue}`;
+  const panelId = `${tabsId}-panel-${panelValue}`;
+
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  const { transitionProps } = useTransition({
+    open: isSelected,
+    ref: panelRef,
+  });
+
+  // Suppress enter animation on initial mount so the initially-selected panel
+  // appears instantly. After the panel has been deselected once, subsequent
+  // selections will animate normally. Matches the Accordion pattern.
+  const hasBeenDeselected = useRef(false);
+  if (!isSelected) hasBeenDeselected.current = true;
+
+  const effectiveTransitionProps =
+    shouldForceMount && !hasBeenDeselected.current
+      ? { ...transitionProps, 'data-cl-starting-style': undefined, style: undefined }
+      : transitionProps;
+
+  const state = { hidden: !isSelected };
+
+  const defaultProps = {
+    'data-cl-slot': 'tabs-panel',
+    id: panelId,
+    role: 'tabpanel' as const,
+    'aria-labelledby': tabId,
+    tabIndex: 0,
+    inert: !isSelected || undefined,
+    hidden: !isSelected && !shouldForceMount ? true : undefined,
+    ...(shouldForceMount
+      ? {
+          ref: panelRef,
+          ...effectiveTransitionProps,
+          style: { ...effectiveTransitionProps.style, ['--cl-tab-transition-direction' as string]: String(direction) },
+        }
+      : {}),
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    state,
+    stateAttributesMapping: {
+      hidden: (v: boolean) => (v ? { 'data-cl-hidden': '' } : null),
+    },
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tabs.Trigger
+// ---------------------------------------------------------------------------
+
+export interface TabsTriggerProps extends ComponentProps<'button'> {
+  value: string;
+  disabled?: boolean;
+}
+
+function TabsTrigger(props: TabsTriggerProps) {
+  const { render, value: tabValue, disabled, ...otherProps } = props;
+  const { value: selectedValue, setValue, tabsId, registerTab } = useTabsContext();
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const isSelected = selectedValue === tabValue;
+  const tabId = `${tabsId}-tab-${tabValue}`;
+  const panelId = `${tabsId}-panel-${tabValue}`;
+
+  useLayoutEffect(() => {
+    registerTab(tabValue, triggerRef.current);
+    return () => registerTab(tabValue, null);
+  }, [tabValue, registerTab]);
+
+  const state = {
+    selected: isSelected,
+    disabled: !!disabled,
+  };
+
+  const defaultProps = {
+    'data-cl-slot': 'tabs-trigger',
+    ref: triggerRef,
+    id: tabId,
+    role: 'tab' as const,
+    type: 'button' as const,
+    'aria-selected': isSelected,
+    'aria-controls': panelId,
+    'aria-disabled': disabled || undefined,
+    onClick: () => {
+      if (!disabled) setValue(tabValue);
+    },
+  };
+
+  return renderElement({
+    defaultTagName: 'button',
+    render,
+    state,
+    stateAttributesMapping: {
+      selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+      disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+    },
+    props: mergeProps<'button'>(defaultProps, otherProps),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tabs.Indicator
+// ---------------------------------------------------------------------------
+
+export interface TabsIndicatorProps extends ComponentProps<'span'> {}
+
+function TabsIndicator(props: TabsIndicatorProps) {
+  const { render, ...otherProps } = props;
+  const { value, getTabElement, orientation, listRef } = useTabsContext();
+
+  const [style, setStyle] = useState<React.CSSProperties>({});
+  const previousRectRef = useRef<{
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  } | null>(null);
+
+  useEffect(() => {
+    const el = getTabElement(value);
+    const list = listRef.current;
+    if (!el || !list) return;
+
+    const tabRect = el.getBoundingClientRect();
+    const listRect = list.getBoundingClientRect();
+
+    const newRect = {
+      left: tabRect.left - listRect.left,
+      top: tabRect.top - listRect.top,
+      width: tabRect.width,
+      height: tabRect.height,
+    };
+
+    const prev = previousRectRef.current;
+    previousRectRef.current = newRect;
+
+    if (orientation === 'horizontal') {
+      setStyle({
+        position: 'absolute',
+        left: newRect.left,
+        width: newRect.width,
+        ['--cl-tab-left' as string]: `${newRect.left}px`,
+        ['--cl-tab-width' as string]: `${newRect.width}px`,
+        ['--cl-tab-top' as string]: `${newRect.top}px`,
+        ['--cl-tab-height' as string]: `${newRect.height}px`,
+        ...(prev == null ? { transition: 'none' } : {}),
+      });
+    } else {
+      setStyle({
+        position: 'absolute',
+        top: newRect.top,
+        height: newRect.height,
+        ['--cl-tab-left' as string]: `${newRect.left}px`,
+        ['--cl-tab-width' as string]: `${newRect.width}px`,
+        ['--cl-tab-top' as string]: `${newRect.top}px`,
+        ['--cl-tab-height' as string]: `${newRect.height}px`,
+        ...(prev == null ? { transition: 'none' } : {}),
+      });
+    }
+  }, [value, getTabElement, orientation, listRef]);
+
+  const defaultProps = {
+    'data-cl-slot': 'tabs-indicator',
+    'aria-hidden': true as const,
+    style,
+  };
+
+  return renderElement({
+    defaultTagName: 'span',
+    render,
+    props: mergeProps<'span'>(defaultProps, otherProps),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Compound export
+// ---------------------------------------------------------------------------
+
+export const Tabs = Object.assign(TabsRoot, {
+  List: TabsList,
+  Tab: TabsTab,
+  Trigger: TabsTrigger,
+  Panel: TabsPanel,
+  Indicator: TabsIndicator,
+});
diff --git a/packages/headless/vite.config.ts b/packages/headless/vite.config.ts
index f89462fe606..613b6ea8e6a 100644
--- a/packages/headless/vite.config.ts
+++ b/packages/headless/vite.config.ts
@@ -12,6 +12,7 @@ export default defineConfig({
     lib: {
       entry: {
         'primitives/accordion/index': 'src/primitives/accordion/index.ts',
+        'primitives/tabs/index': 'src/primitives/tabs/index.ts',
         'primitives/dialog/index': 'src/primitives/dialog/index.ts',
         'utils/index': 'src/utils/index.ts',
         'hooks/use-controllable-state': 'src/hooks/use-controllable-state.ts',