# Tabs
> Switch between related panels while keeping the same page context.
Source: https://www.honestui.com/docs/components/tabs
```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/honest-ui/ui/tabs"
export function TabsDemo() {
return (
Tab 1Tab 2Tab 3
Tab 1 content
Tab 2 content
Tab 3 content
)
}
```
## Overview [#overview]
Use Tabs to switch between peer panels without leaving the current page: settings sections, profile views, code examples in different languages, billing periods. Tabs tell people "these are alternative views of the same object" — only one is visible at a time, and switching costs nothing.
Tabs are the wrong tool when panels are steps in a sequence (use a wizard with Back and Next), when people need to compare panels side by side, or when each panel deserves its own URL that can be linked and revisited. If tabs must deep-link, mirror the active tab into the route. See [Don't do this](#dont-do-this).
## Anatomy [#anatomy]
Tabs include a root, a list with an animated indicator, one trigger per tab, and one panel per tab. The trigger labels name their panels; every `value` on a `TabsTab` must match exactly one `TabsPanel` value or the panel will never appear. The indicator slides between triggers to show which panel is active, and it works in both orientations and all variants.
## Behavior [#behavior]
**Orientation.** Horizontal is the default. Use vertical tabs when labels are long or numerous enough that a horizontal row would wrap or truncate — a vertical list keeps every label fully visible.
**Activation mode.** By default activation is manual: arrow keys move focus between triggers, and Enter, Space, or a click activates the focused tab. Set `activateOnFocus` on the `TabsList` for automatic activation, where focusing a trigger immediately switches the panel. Reserve automatic mode for panels that render instantly; manual mode prevents slow panels from flashing past while someone arrows across the list.
**Controlled state.** Pass `value` and `onValueChange` to sync the active tab with routing or other page state. Passing `null` as the value renders no active tab at all.
## Accessibility [#accessibility]
The list has `role="tablist"` and each trigger has `role="tab"` with `aria-selected` and `aria-controls` pointing at its panel, so screen readers announce position within the set.
Focus follows a roving model: the whole list is a single Tab stop, and Tab again moves into the active panel. Within the list:
* ArrowLeft and ArrowRight move between tabs in horizontal orientation; ArrowUp and ArrowDown in vertical. Directions mirror automatically in right-to-left layouts.
* Home and End jump to the first and last tab.
* Movement wraps from end to end by default; set `loopFocus={false}` on the list to stop at the edges.
* Enter or Space activates the focused tab under manual activation.
Disabled triggers remain focusable and announced but cannot be activated. Colors come from theme tokens, so active, hover, and disabled states adapt to dark mode automatically.
Trigger labels use `white-space: nowrap` with ellipsis overflow: long labels are silently cut off rather than wrapped. Keep labels to one or two words, or switch to vertical orientation where there is room to grow.
## Installation [#installation]
Copy and paste the following code into your project.
### components/ui/tabs.tsx
```tsx
"use client"
import { Tabs as TabsPrimitive } from "@base-ui-components/react/tabs"
import { cn } from "@/lib/utils"
type TabsSize = "small" | "medium" | "large" | "regular"
type TabsVariant = "default" | "underline" | "standalone" | "plain"
function Tabs({
size = "large",
className,
...props
}: TabsPrimitive.Root.Props & { size?: TabsSize }) {
return (
)
}
function TabsList({
variant = "default",
indicatorClassName,
className,
children,
...props
}: TabsPrimitive.List.Props & {
variant?: TabsVariant
indicatorClassName?: string
}) {
const resolvedVariant = variant === "underline" ? "plain" : variant
return (
[data-slot=tabs-trigger]]:border-[0.5px] [&>[data-slot=tabs-trigger]]:border-[var(--hui-color-border-base-primary)] [&>[data-slot=tabs-trigger][data-active]]:border-transparent",
resolvedVariant === "plain" &&
"justify-center gap-[var(--hui-space-6)] rounded-none bg-transparent p-0 shadow-none [&>[data-slot=tabs-trigger]]:flex-none [&>[data-slot=tabs-trigger]]:rounded-none [&>[data-slot=tabs-trigger]]:border-b [&>[data-slot=tabs-trigger]]:border-b-transparent",
className
)}
{...props}
>
{children}
)
}
function TabsTab({ className, ...props }: TabsPrimitive.Tab.Props) {
return (
)
}
function TabsPanel({ className, ...props }: TabsPrimitive.Panel.Props) {
return (
)
}
export {
Tabs,
TabsList,
TabsTab,
TabsTab as TabsTrigger,
TabsPanel,
TabsPanel as TabsContent
}
```
Update the import paths to match your project setup.
## Usage [#usage]
```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/ui/tabs";
```
```tsx
Tab 1 content
Tab 2 content
Tab 3 content
```
`TabsTrigger` and `TabsContent` are aliases of `TabsTab` and `TabsPanel`. Style panels independently — the component imposes no panel layout of its own.
## Don't do this [#dont-do-this]
### Using tabs for page navigation [#using-tabs-for-page-navigation]
```tsx
// Bad
...
```
```tsx
// Good
```
Tabs switch in-view content; they do not navigate. A tabbed site header breaks browser Back, cannot be opened in a new tab, hides every page from direct linking, and announces itself as a tab set rather than navigation. Top-level destinations belong in links and nav landmarks. If sections genuinely share a URL-able route, sync the active tab to the router instead of relying on local state alone.
### Sequencing steps as tabs [#sequencing-steps-as-tabs]
```tsx
// Bad
```
```tsx
// Good
{/* Step 1, then step 2 with Next/Back */}
```
Tabs imply equal peers that can be visited in any order. Checkout steps have order, dependencies, and validation: jumping straight to Payment skips required Shipping data. Sequential flows need explicit progression with validation between steps.
### Overloading the tab bar [#overloading-the-tab-bar]
```tsx
// Bad
Notifications and email preferences
```
```tsx
// Good
Notifications
```
Trigger text does not wrap; it truncates with an ellipsis once it outgrows the bar, so both sighted and screen-reader users lose the tail of the label. Keep each label short and unique, and split genuinely distinct concerns into more tabs rather than longer names.
## Examples [#examples]
### Settings sections [#settings-sections]
Two peer panels with independent, short labels — the canonical settings shape.
```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/honest-ui/ui/tabs"
export function TabsSettings() {
return (
ProfileSecurityUpdate your public workspace profile.Manage sessions and two-factor settings.
)
}
```
### Underline Variant [#underline-variant]
A quieter treatment for content pages: no filled background, just an animated underline marking the active tab.
```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/honest-ui/ui/tabs"
export function TabsUnderline() {
return (
Tab 1Tab 2Tab 3
Tab 1 content
Tab 2 content
Tab 3 content
)
}
```
### Vertical Orientation [#vertical-orientation]
Longer label lists read better down the side; arrow keys switch to Up and Down automatically.
```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/honest-ui/ui/tabs"
export function TabsVertical() {
return (
Tab 1Tab 2Tab 3
Tab 1 content
Tab 2 content
Tab 3 content
)
}
```
### Underline with Vertical Orientation [#underline-with-vertical-orientation]
The underline variant composed with a vertical list.
```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/honest-ui/ui/tabs"
export function TabsUnderlineVertical() {
return (
Tab 1Tab 2Tab 3
Tab 1 content
Tab 2 content
Tab 3 content
)
}
```
## API reference [#api-reference]
`Tabs`, `TabsList`, `TabsTab`, and `TabsPanel` forward their matching Base UI props. Root props include `value`, `defaultValue`, `onValueChange`, and `orientation` (`"horizontal"` default, `"vertical"`); passing `value={null}` leaves no tab active.
Honest UI additions:
| Prop | Component | Values | Default |
| -------------------- | ---------- | ----------------------------------------------------- | ----------- |
| `size` | `Tabs` | `"small"`, `"medium"`, `"large"`, `"regular"` | `"large"` |
| `variant` | `TabsList` | `"default"`, `"underline"`, `"standalone"`, `"plain"` | `"default"` |
| `indicatorClassName` | `TabsList` | string | — |
`small` and `medium` reduce trigger height, font size, and letter spacing for dense surfaces; `large` and `regular` currently share the same base metrics. `variant="underline"` renders a borderless list with a sliding bottom indicator, `standalone` draws individual bordered chips with a raised active card, and `plain` is the underline style used internally. Set `activateOnFocus` and `loopFocus` on `TabsList` to change keyboard behavior.
See the [Base UI Tabs API](https://base-ui.com/react/components/tabs#api-reference).