Tabs
Switch between peer views of the same content without leaving the page; one view shows at a time.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add tabsAlso works with shadcn:
npx shadcn@latest add @ritla/tabsDependencies it brings
@base-ui/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Tab, Tabs, TabsList, TabsPanel } from "@/components/ui/tabs";<Tabs defaultValue="overview"> <TabsList aria-label="Account"> <Tab value="overview">Overview</Tab> <Tab value="transactions">Transactions</Tab> </TabsList> <TabsPanel value="overview">…</TabsPanel> <TabsPanel value="transactions">…</TabsPanel></Tabs>Examples
Vertical
A column for settings on wide screens that becomes a sideways scrolling row on a phone.
Icons and badges
An icon on every tab or none, and a count after the label.
Breakpoints
breakpoint pins the desktop (16) or mobile (14) size; the default auto follows the screen.
Neutral tone
tone="neutral" is a gray selection for quieter surfaces. The selected Button tab takes a thin border/gray/strong ring so it still reads at 3:1, and the Underline keeps the brand line.
API reference
Tabs
| Prop | Type | Default | Description |
|---|---|---|---|
type | "underline" | "button" | "underline" | Figma's Type: a line under the selected tab, or a fill on it. |
orientation | "horizontal" | "vertical" | "horizontal" | Figma's Horizontal tabs or Vertical tabs. |
breakpoint | "auto" | "desktop" | "mobile" | "auto" | Figma's Breakpoint. auto is the mobile size below md and desktop from md; vertical tabs become a row on a phone. |
dividers | boolean | true | Figma's Show line divider: lines between horizontal Button tabs. |
tone | "brand" | "neutral" | "brand" | Figma's Tone: a brand or a gray selection. |
value / defaultValue | string | None | The selected tab (controlled or initial). |
onValueChange | (value) => void | None | Called when a tab is selected. |
TabsList
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label | string | None | The tab set's name for screen readers. |
activateOnFocus | boolean | true | Selects a tab as soon as the arrows reach it. Turn off when a panel is slow to load. |
Tab
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | None | Matches its panel's value. |
children | ReactNode | None | Figma's Label: one or two words, on one line. |
iconLeading | IconComponent | None | Figma's Icon and Leading icon. |
badge | number | string | None | Figma's Badge and its Count: a Brand badge after the label. |
disabled | boolean | false | Not in Figma: a tab you can't select yet. |
TabsPanel
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | None | Matches its tab's value; hidden unless its tab is selected. |
Usage guidelines
Tabs show peer views of one subject, one view at a time. When they fit, which type and orientation, how to write labels, what to do when there are many, how they start from the right in Arabic, and the checks before handoff.
1. Tabs, or another structure
Tabs fit when one subject has a few peer views and people look at one at a time: an account's Overview, Transactions and Statements. If the views are steps, places or filters, another component says it better.
| You need to | Use | Why |
|---|---|---|
| Show peer views of one subject | Horizontal tabs | One view at a time, same page, same header. |
| Sections of a long settings page on desktop | Vertical tabs | A column that fits many sections; a row on phones. |
| Walk through steps in order | Progress steps | Tabs imply you can jump anywhere. |
| Filter or switch the layout of a list | Toggle group or filter chips | They change the same content, not the view. |
| Go to another page or area of the app | Navigation or links | Tabs keep people on this page. |
2. Type and orientation
Underline tabs sit at the top of a page or card and read as its sections. Button tabs are a compact bar for toolbars and panels. Vertical tabs hold many sections beside the content on desktop and become a sideways row on phones. The Breakpoint sets the size; in code auto follows the screen.
| Type | Use |
|---|---|
| Underline | Sections of a page or a card; the default. |
| Button | Compact bars in toolbars, panels and dense layouts. |
Do
- Use Underline for page sections, Button for compact bars.
- Use Vertical tabs for settings with many sections on desktop.
- Use one type per page.
Don't
- Stack two rows of tabs.
- Mix Underline and Button tabs on one screen.
3. Labels and icons
Labels are one or two words, nouns of the same kind, on one line: Overview, Transactions, Statements. Icons are optional; use them on every tab or none. A badge counts something new inside a tab.
Icons on all tabs or none
An account page.
Do
- Name each view in one or two words.
- Use icons on every tab or on none.
- Keep the tab order the same every time the page loads.
- Use a badge for a count inside the tab: Requests 3.
Don't
- Wrap a label onto two lines.
- Give only some tabs an icon.
- Use verbs or sentences as tab labels.
4. Many tabs
Keep a horizontal bar to about five tabs so they all fit. When there are more, the list scrolls sideways in code and keeps the selected tab in view; on desktop, consider Vertical tabs instead. Never let tabs wrap to a second row.
Do
- Keep about five tabs in a horizontal bar.
- Let the bar scroll sideways when it must, with the selected tab in view.
- Switch to Vertical tabs for long lists of sections on desktop.
Don't
- Shrink labels or truncate them to fit more tabs.
- Hide tabs behind a More tab.
- Wrap tabs onto two rows.
5. Arabic and RTL
The RTL variants start from the right: the first tab sits at the right edge and the order runs to the left. Arrow keys follow the reading direction, so ArrowLeft moves to the next tab in Arabic. Vertical tabs put the list and its indicator on the right. Arabic labels often run longer; check they stay on one line.
Tabs start from the right
An account page in Arabic.
Before handoff
- Tabs only for peer views of one subject.
- One type per page; Vertical tabs for long settings on desktop.
- Labels are one or two words; icons on all or none.
- Arabic screens use RTL variants, starting from the right.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | Enters the list on the selected tab; the next press moves to the panel. |
| ArrowRightArrowLeft | Moves to the next or previous tab and selects it, wrapping at the ends. Flips in Arabic; vertical tabs use ArrowDown and ArrowUp. |
| HomeEnd | Jumps to the first or last tab. |
ARIA
- A
role="tablist"named byaria-label; eachrole="tab"carriesaria-selectedand controls itsrole="tabpanel". - The icon is decorative; the badge count is part of the tab's name.
- In the Neutral tone Figma's gray fill is only 1.16:1 against the bar, so the selected tab takes a thin
border/gray/strongring that reaches 3:1. - For moving between pages or steps, use links or a stepper, not tabs.
Do
- Name the tab list: “Account”.
- Tab enters on the selected tab; arrows move; Home and End jump to the ends.
- Select on arrow when panels show instantly; otherwise with Enter or Space.
- Mark the selected tab by more than color: a line or a pill.
Don't
- Make each tab its own Tab stop.
- Load a new page when a tab is pressed.
Arabic and RTL notes
Mirrors
- The first tab sits on the right, and the arrows flip: ArrowLeft is next.
- Vertical tabs put the column and the selected line on the right, with the panel to its left.
- A scrolling row starts at the right and scrolls to the left.
Does not mirror
- Decorative icons stay as drawn, except directional ones on the mirror list.
- Numerals
- The badge count follows the numerals setting (
0123456789or٠١٢٣٤٥٦٧٨٩). - Arabic typography
body-16orbody-14Semibold, with a minimum height rather than a fixed one: Arabic lines are taller.- Mixed-direction text
- Tab labels never wrap onto two lines. Put an English brand name inside an Arabic label in
<bdi>.
Do
- The RTL variant, with the first tab on the right.
- The same order as English, running right to left.
- Check that the longest Arabic label fits on one line.
Don't
- English tabs on an Arabic screen.
- Reverse the order by hand in the English variant.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)