---
title: "TabBar"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/tab-bar"
source: "https://opsinjs.pensievelabs.org/docs/components/tab-bar.md"
section: "Components"
status: "shipped"
kind: "component"
category: "navigation"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["bottom navigation", "nav bar"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="tab-bar"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured for the current-destination treatment against the overlay material, so whether it reads as current in greyscale is unverified.&#x22;,
  &#x22;Nobody has listened to this bar in a screen reader, so whether the landmark, the item count and the current state are announced is unchecked.&#x22;,
  &#x22;Forced colours and prefers-contrast: more are unhandled, and whether the current destination survives a palette that replaces both carriers has not been tested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="tab-bar" unbuilt="false" importPath="@/components/ui/tab-bar" dependencies="[&#x22;lucide-react&#x22;]" registryDependencies="[&#x22;surface&#x22;]" />

```tsx
import { TabBar } from "@/components/ui/tab-bar"
```

```tsx
<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 [#examples]

<ComponentPreview name="tab-bar" />

### Four destinations [#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`.

<ComponentPreview name="tab-bar-four-destinations" kind="example" align="start" />

### Destinations as links [#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.

<ComponentPreview name="tab-bar-with-links" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Moving between two to five top-level sections of a phone app, where the destinations are peers.&#x22;,
  &#x22;Keeping the whole set of destinations in view, so any section is one tap away.&#x22;,
]"
  avoid="[
  { case: &#x22;Switching between views that live inside one screen and share its space.&#x22;, instead: &#x22;tabs&#x22; },
  { case: &#x22;Setting one parameter of a single view, such as a chart's day or week window.&#x22;, instead: &#x22;segmented-control&#x22; },
  { case: &#x22;More than five destinations, or a \&#x22;More\&#x22; tab, which buries a safety relevant action.&#x22;, instead: &#x22;menu&#x22; },
]"
/>

## Accessibility [#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.

<KeyboardTable
  name="tab-bar"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus to the next destination&#x22;,
    notes: &#x22;Each destination is its own tab stop, not a roving one.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus to the previous destination&#x22;,
    notes: &#x22;Focus steps back one destination at a time, in reverse order.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Activates the focused destination&#x22;,
    notes: &#x22;An anchor follows its href; a button reports the key through onValueChange.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Activates a button destination&#x22;,
    notes: &#x22;Native anchor behaviour, so Space does not activate a link destination.&#x22;,
  },
  {
    keys: &#x22;Home, End&#x22;,
    action: &#x22;Not bound&#x22;,
    notes: &#x22;The bar adds no roving-focus keys, so the browser default stands.&#x22;,
  },
]"
/>

<ContrastReport component="tab-bar" />

## Props interface [#props-interface]

<PropsTable name="TabBarProps" />

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