Tab

Installation

npx axiom add tab

pnpm dlx axiom add tab

yarn dlx axiom add tab

bun x axiom add tab

Also copies: icon, badge, text, tappable and useControllableState. Installs react-native-reanimated.

Colors come from tab.{underline,pill}.{default,selected,disabled} in the component tokens.

Usage

import { Tab } from "@/components/ui/tab";

<Tab value={section} onValueChange={setSection}>
	<Tab.List>
		<Tab.Item value="all">All</Tab.Item>
		<Tab.Item value="unread">Unread</Tab.Item>
		<Tab.Item value="archived">Archived</Tab.Item>
	</Tab.List>

	<Tab.Content>
		<Tab.Panel value="all">
			<Feed />
		</Tab.Panel>
		<Tab.Panel value="unread">
			<UnreadFeed />
		</Tab.Panel>
		<Tab.Panel value="archived">
			<Archive />
		</Tab.Panel>
	</Tab.Content>
</Tab>;

Props

Tab

Tab.List

Tab.List renders a View by default. With scrollable, it renders a horizontal ScrollView and keeps each item at its natural width.

Tab.Item

Tab.Content

Tab.Content is a View. It renders only the selected Tab.Panel.

Tab.Pager

Tab.Pager is a horizontal ScrollView with pagingEnabled. Use it instead of Tab.Content when users should be able to swipe between panels.

Tab.Panel

The indicator travels on a spring, and lands without animating the first time: it has nothing to travel from until the items have been measured. Reduced motion moves it without animation. Inside a Tab.Pager, the indicator follows the finger instead: its position and width track the pager’s scroll on the UI thread.

Tab sets the tab list, tab and selected accessibility roles. Panels are optional. Without Tab.Content or Tab.Pager, the screen can render its content elsewhere from the selected value.

Haptics

Tabs play nothing by default. Pass a kind to Tab, usually "selection", to play one when the user changes the tab, by pressing an item or by swiping the pager. A value changed in code plays nothing. Nothing plays until your app connects a haptics library: see Haptics.

Swipe to switch

Use Tab.Pager when the panels contain peer views such as feeds, inboxes or order lists. Use Tab.Content when a panel owns horizontal interaction, for example a carousel, a pannable chart or rows with swipe actions.

<Tab value={section} onValueChange={setSection} style={{ flex: 1 }}>
	<Tab.List>
		<Tab.Item value="all">All</Tab.Item>
		<Tab.Item value="mentions">Mentions</Tab.Item>
	</Tab.List>

	<Tab.Pager>
		<Tab.Panel value="all">
			<Feed />
		</Tab.Panel>
		<Tab.Panel value="mentions">
			<Mentions />
		</Tab.Panel>
	</Tab.Pager>
</Tab>

The pager needs a bounded width and height. It uses the native ScrollView paging behavior, measures each panel at runtime and updates the selected value when scrolling settles. Pressing a tab scrolls to the measured position of its panel. Off-screen panels stay hidden from the screen reader.

Tab.Pager passes its props to the underlying ScrollView, so scrollEnabled, decelerationRate, keyboard behavior and the momentum callbacks remain configurable. onScroll is the exception: the pager’s scroll drives the indicator, so it keeps that handler for itself.

Use cases

Switching one data view

Tabs work when the content changes but the screen purpose stays the same. Keep the filter state local to the screen.

<Tab value={status} onValueChange={setStatus}>
	<Tab.List>
		<Tab.Item value="active">Active</Tab.Item>
		<Tab.Item value="past">Past</Tab.Item>
	</Tab.List>
</Tab>

Categories that need horizontal scrolling

When labels cannot fit without shrinking, let the row scroll. The selected tab should be brought into view after selection.

<Tab value={category} onValueChange={setCategory}>
	<Tab.List scrollable>
		{categories.map((item) => (
			<Tab.Item key={item.id} value={item.id}>
				{item.label}
			</Tab.Item>
		))}
	</Tab.List>
</Tab>

Compact mode switch with pills

The pill variant works for a short, local mode switch. For two or three equally sized options inside a form, prefer SegmentedControl.

<Tab value={view} onValueChange={setView}>
	<Tab.List variant="pill">
		<Tab.Item value="grid" icon="grid">
			Grid
		</Tab.Item>
		<Tab.Item value="map" icon="map">
			Map
		</Tab.Item>
	</Tab.List>
</Tab>

Related

• BottomTabBar, for top-level destinations
• SegmentedControl, for compact form choices
• Badge