Content Switcher
Switches at once between 2 to 4 views or filters of the same content, like Day, Week and Month (up to 6 periods in the pill styles); exactly one option is selected.
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 content-switcherAlso works with shadcn:
npx shadcn@latest add @ritla/content-switcherDependencies 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 { ContentSwitcher, ContentSwitcherItem } from "@/components/ui/content-switcher";<ContentSwitcher aria-label="Period" defaultValue="day"> <ContentSwitcherItem value="day">Day</ContentSwitcherItem> <ContentSwitcherItem value="week">Week</ContentSwitcherItem> <ContentSwitcherItem value="month">Month</ContentSwitcherItem></ContentSwitcher>Examples
Counts and icons
A count after the label, or icons alone with the label kept for screen readers (showLabel={false}).
Disabled
One option that isn't available yet, then the whole switcher.
Neutral tone
tone="neutral" fills the selected option with the inverse surface, for screens where a brand fill would compete with the page's main action.
Pill styles
variant="pill-segmented" is a gray track with a raised option, variant="pills" separate pills. Size sm and Neutral only, as Figma draws them, with up to 6 periods. Write Arabic periods as words, not Latin abbreviations; the row scrolls sideways when it doesn't fit.
API reference
ContentSwitcher
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "md" | "lg" | "sm" | Figma's Size: 32, 40 or 48px. |
value / defaultValue | string | None | The selected option (controlled or initial). Figma selects the first. |
onValueChange | (value: string) => void | None | Called when an option is selected. |
dividers | boolean | true | Figma's Divider: lines between resting options (Default only). |
tone | "brand" | "neutral" | "brand" | Figma's Tone. The pill styles are always Neutral. |
variant | "default" | "pill-segmented" | "pills" | "default" | Figma's Style. The pill styles are size sm, so size doesn't apply to them. |
disabled | boolean | false | Disables every option. |
aria-label | string | None | The choice's name for screen readers ("Period"). |
ContentSwitcherItem
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | None | The option's value in the switcher. |
children | ReactNode | None | Figma's Label: one short word; still the option's name when hidden. |
showLabel | boolean | true | Figma's Show label. Off leaves the icon alone. |
iconLeading | IconComponent | None | Figma's Icon: a 16px icon in the label's color. |
badge | number | string | None | Figma's Badge and its Count: Gray, Brand on the selected option. |
disabled | boolean | false | Figma's State = Disabled for this option. |
Usage guidelines
The content switcher changes how the content right below it is shown. When to pick it, how to write its options, which size, how it starts from the right in Arabic, and the checks before handoff.
1. Content switcher, or something else
Use the content switcher to change how the content right below it is shown: a chart by period, a list by status, a map or a list. It applies at once. Use it inside cards, charts and panels, and Toggle group in toolbars next to Buttons.
| You need to | Use | Why |
|---|---|---|
| Switch a chart or card between 2 to 4 views | Content switcher | Light, compact and sits inside the content. |
| Switch a view in a toolbar, next to Buttons | Toggle group | Matches the Button styles and sizes. |
| Split a page into sections | Tabs | Tabs own panels and read as page structure. |
| Choose an option that is saved with a form | Radio group | Radios wait for Submit. |
| Choose from more than four options | Select or Tabs | A segmented row gets cramped past four. |
2. Options and labels
Two to four options, one short word each, of similar length so the segments look even. The first option is selected by default. Icons are optional: on every option or none. Icon-only options keep their label as the accessible name.
Short, even options
The period switcher above a spending chart.
Do
- Use one word per option: Day, Week, Month, Year.
- Keep labels of similar length.
- Select the most useful option first.
Don't
- Use more than four options.
- Mix a long phrase with one-word options.
- Show icons on only some options.
3. Size
sm (32) fits inside cards and chart headers, md (40) is the default, lg (48) suits touch-heavy screens. sm and md add an invisible 48 px hit area in code. Match the height of the controls next to it.
Do
- Use
smin card and chart headers. - Match the size of neighboring controls.
Don't
- Use
lgin a dense card header. - Stretch the switcher to full width on desktop.
4. Arabic and RTL
The RTL variant starts from the right: the first option, selected by default, sits on the right, and the rounded ends follow the reading direction. Arrow keys follow it too, so ArrowLeft moves to the next option in Arabic. Keep the same option order as English.
The first option is on the right
The period switcher in Arabic.
Before handoff
- 2 to 4 options that change the content right below.
- One-word labels of similar length; the first is selected.
- The size matches its neighbors.
- Arabic screens use the RTL variant.
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 switcher once, on the selected option; the next press leaves it. |
| ArrowRightArrowLeft | Moves the selection to the next or previous option, wrapping at the ends. Flips in Arabic. |
| Space | Selects the focused option. |
ARIA
- A
role="radiogroup"named byaria-label; each option is arole="radio"witharia-checked. - Selection doesn't rely on color alone: the selected option is filled in the brand color, the others are outlined.
- In Pill segmented the selected option takes a thin
border/gray/strongring, since its white segment is only 1.16:1 against the track. - For moving between pages use Tabs; for settings that get saved use Radio buttons.
Do
- Name the switcher: “Period”.
- Tab enters on the selected option; arrows move the selection and follow the reading direction.
- A label on every option, even an icon-only one.
Don't
- Use it to navigate to other pages.
- Rely on the fill color alone; the selected option also has a stronger label.
Arabic and RTL notes
Mirrors
- The first option sits on the right, and the rounded ends follow.
- The arrows flip: ArrowLeft is next.
- Each divider sits on the option's end edge: its left in Arabic.
Does not mirror
- Chart and table icons stay as drawn.
- Numerals
- Badge counts follow the numerals setting.
- Arabic typography
label-14Medium in the display family, with a minimum height rather than a fixed one: Arabic lines are taller.- Mixed-direction text
- Labels never wrap; keep them to one word of similar length.
Do
- The RTL variant, with the first option on the right.
- The same order as English, running right to left.
- One-word Arabic options: «يوم» for Day.
Don't
- The English switcher on an Arabic screen.
- Reverse the options 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)