Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
tab-bar · base base · style base-lyraOpen under the product theme

Four 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.

Theme
Density
Text
Status
Accent theme
Accent
tab-bar-four-destinations · base base · style base-lyraOpen under the product theme
tab-bar-four-destinations.tsx
"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>
  )
}

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.

Theme
Density
Text
Status
Accent theme
Accent
tab-bar-with-links · base base · style base-lyraOpen under the product theme
tab-bar-with-links.tsx
"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 tabs instead.
  • Setting one parameter of a single view, such as a chart's day or week window.Use segmented-control instead.
  • More than five destinations, or a "More" tab, which buries a safety relevant action.Use menu instead.

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-motion guard, which still meets AA because that guard is an AAA item.
  • A forced-colors repaint may flatten the indicator bar, but font-weight and aria-current keep 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.
KeyActionNotes
TabMoves focus to the next destinationEach destination is its own tab stop, not a roving one.
Shift+TabMoves focus to the previous destinationFocus steps back one destination at a time, in reverse order.
EnterActivates the focused destinationAn anchor follows its href; a button reports the key through onValueChange.
SpaceActivates a button destinationNative anchor behaviour, so Space does not activate a link destination.
Home, EndNot boundThe bar adds no roving-focus keys, so the browser default stands.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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.