Components
TabBar
The persistent bar of top-level destinations at the foot of a phone screen. It marks the current one with a heavier label and a top indicator, not colour.
Usage
pnpm dlx shadcn@latest add @opsinjs/tab-bar
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { TabBar } from "@/components/ui/tab-bar"<TabBar
label="Main sections"
value={section}
onValueChange={setSection}
items={[
{ key: "home", label: "Home", icon: <House /> },
{ key: "trends", label: "Trends", icon: <Activity /> },
{ key: "learn", label: "Learn", icon: <BookOpen /> },
{ key: "settings", label: "Settings", icon: <Settings /> },
]}
/>Examples
tab-bar · base base · style base-lyraOpen under the product themeFour destinations
Four peer destinations, each an icon over a one-word label, with one current.
onValueChange reports the chosen key, which the screen passes back as
value.
tab-bar-four-destinations · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Activity, GraduationCap, House, User } from "lucide-react"
import { TabBar } from "@/components/ui/tab-bar"
export default function TabBarFourDestinations() {
const [section, setSection] = useState("home")
return (
<div className="w-full max-w-sm">
<TabBar
label="Example sections"
value={section}
onValueChange={setSection}
items={[
{ key: "home", label: "Home", icon: <House /> },
{ key: "trends", label: "Trends", icon: <Activity /> },
{ key: "learn", label: "Learn", icon: <GraduationCap /> },
{ key: "profile", label: "Profile", icon: <User /> },
]}
/>
</div>
)
}Destinations as links
An href on each item builds the bar from anchors, so a product router acts on
the navigation. Pinned through className, with safe-area padding clearing the
home indicator.
tab-bar-with-links · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Bookmark, Compass, House, User } from "lucide-react"
import { TabBar } from "@/components/ui/tab-bar"
export default function TabBarWithLinks() {
const [section, setSection] = useState("home")
return (
<div className="relative h-96 w-full max-w-sm overflow-hidden rounded-opsin-lg border border-border bg-background">
<div className="h-full overflow-y-auto p-opsin-4">
<p className="m-0 text-opsin-body">
Example screen content sits above the bar and scrolls beneath it.
The bar stays pinned to the foot of the frame.
</p>
</div>
<TabBar
className="absolute inset-x-0 bottom-0"
label="Example destinations"
value={section}
onValueChange={setSection}
items={[
{ key: "home", label: "Home", icon: <House />, href: "#home" },
{ key: "explore", label: "Explore", icon: <Compass />, href: "#explore" },
{ key: "saved", label: "Saved", icon: <Bookmark />, href: "#saved" },
{ key: "profile", label: "Profile", icon: <User />, href: "#profile" },
]}
/>
</div>
)
}When to use it
Use it when
- Moving between two to five top-level sections of a phone app, where the destinations are peers.
- Keeping the whole set of destinations in view, so any section is one tap away.
Do not use it when
- Switching between views that live inside one screen and share its space.Use
tabsinstead. - Setting one parameter of a single view, such as a chart's day or week window.Use
segmented-controlinstead. - More than five destinations, or a "More" tab, which buries a safety relevant action.Use
menuinstead.
Accessibility
Confirmed: a real nav landmark named by label, and icons aria-hidden with the
label as the accessible name. The current destination carries aria-current="page",
a heavier label and a top indicator, so no cue rides on colour. Every target is
floored at the 44pt minimum in rem. Axe, target-size, focus and 320px reflow checks
were clean, and the audit changed nothing.
Residual items.
- The colour and opacity fades carry no
prefers-reduced-motionguard, which still meets AA because that guard is an AAA item. - A
forced-colorsrepaint may flatten the indicator bar, butfont-weightandaria-currentkeep the current state legible. - A bottom-fixed bar can obscure focused content, but this component owns no position, so SC 2.4.11 is the product's concern.
- Contrast for the current treatment on the overlay material is still unmeasured. See the report below.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the next destination | Each destination is its own tab stop, not a roving one. |
| Shift+Tab | Moves focus to the previous destination | Focus steps back one destination at a time, in reverse order. |
| Enter | Activates the focused destination | An anchor follows its href; a button reports the key through onValueChange. |
| Space | Activates a button destination | Native anchor behaviour, so Space does not activate a link destination. |
| Home, End | Not bound | The bar adds no roving-focus keys, so the browser default stands. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from TabBarProps in registry/bases/base/tab-bar.tsx.
value makes this controlled, with no internal selection state, and a value
matching no item renders nothing current and warns in development.
onValueChange is optional, because a bar of links can leave navigation to the
href. label is required: an unnamed navigation landmark is a defect.