Tabs

A component for toggling between related panels on the same page.

Manage your account settings and preferences.

<ui:tabs.root defaultValue="tab1">
    <ui:tabs.list class="mb-3">
        <ui:tabs.trigger value="tab1">Account</ui:tabs.trigger>
        <ui:tabs.trigger value="tab2">Password</ui:tabs.trigger>
        <ui:tabs.trigger value="tab3">Settings</ui:tabs.trigger>
    </ui:tabs.list>
    <ui:tabs.content value="tab1">
        <div class="aspect-video w-84 rounded-md border-dashed border p-4 text-sm grid place-items-center text-center">
            Manage your account settings and preferences.
        </div>
    </ui:tabs.content>
    <ui:tabs.content value="tab2">
        <div class="aspect-video w-84 rounded-md border-dashed border p-4 text-sm grid place-items-center text-center">
            Change your password and other security options.
        </div>
    </ui:tabs.content>
    <ui:tabs.content value="tab3">
        <div class="aspect-video w-84 rounded-md border-dashed border p-4 text-sm grid place-items-center text-center">
            Configure your application settings and preferences.
        </div>
    </ui:tabs.content>
</ui:tabs.root>

Features

Full keyboard navigation support with arrow keys
Supports horizontal and vertical orientations
Supports automatic and manual tab activation modes
Content is lazy mounted by default
Supports disabled tabs

Anatomy

<primitives:tabs.root>
    <primitives:tabs.list>
        <primitives:tabs.trigger />
        <primitives:tabs.indicator />
    </primitives:tabs.list>
    <primitives:tabs.content />
</primitives:tabs.root>

Installation

typo3 ui:add tabs

Read more about installing Components and Primitives.

Examples

Vertical Orientation

Display tabs in a vertical layout.

Manage your account settings and preferences.

<ui:tabs.root defaultValue="tab1" orientation="{f:constant(name: 'Jramke\FluidPrimitives\Enum\Orientation::Vertical')}" class="flex gap-4">
    <ui:tabs.list class="flex-col h-auto items-end">
        <ui:tabs.trigger value="tab1">Account</ui:tabs.trigger>
        <ui:tabs.trigger value="tab2">Password</ui:tabs.trigger>
        <ui:tabs.trigger value="tab3">Settings</ui:tabs.trigger>
    </ui:tabs.list>
    <div class="flex-1">
        <ui:tabs.content value="tab1">
            <div class="aspect-video w-84 rounded-md border-dashed border p-4 text-sm grid place-items-center text-center">
                Manage your account settings and preferences.
            </div>
        </ui:tabs.content>
        <ui:tabs.content value="tab2">
            <div class="aspect-video w-84 rounded-md border-dashed border p-4 text-sm grid place-items-center text-center">
                Change your password and other security options.
            </div>
        </ui:tabs.content>
        <ui:tabs.content value="tab3">
            <div class="aspect-video w-84 rounded-md border-dashed border p-4 text-sm grid place-items-center text-center">
                Configure your application settings and preferences.
            </div>
        </ui:tabs.content>
    </div>
</ui:tabs.root>

Disabled Tabs

Disable specific tabs to prevent interaction.

First tab content.

<ui:tabs.root defaultValue="tab1">
    <ui:tabs.list class="mb-3">
        <ui:tabs.trigger value="tab1">Enabled 1</ui:tabs.trigger>
        <ui:tabs.trigger value="tab2" disabled="{true}">Disabled</ui:tabs.trigger>
        <ui:tabs.trigger value="tab3">Enabled 2</ui:tabs.trigger>
    </ui:tabs.list>
    <ui:tabs.content value="tab1">First tab content.</ui:tabs.content>
    <ui:tabs.content value="tab2">This tab is disabled.</ui:tabs.content>
    <ui:tabs.content value="tab3">Third tab content.</ui:tabs.content>
</ui:tabs.root>

Manual Activation

Require pressing Enter or Space to activate tabs instead of activating on focus.

Press Enter to switch tabs.

<ui:tabs.root defaultValue="tab1" activationMode="{f:constant(name: 'Jramke\FluidPrimitives\Enum\TabsActivationMode::Manual')}">
    <ui:tabs.list class="mb-3">
        <ui:tabs.trigger value="tab1">Tab 1</ui:tabs.trigger>
        <ui:tabs.trigger value="tab2">Tab 2</ui:tabs.trigger>
        <ui:tabs.trigger value="tab3">Tab 3</ui:tabs.trigger>
    </ui:tabs.list>
    <ui:tabs.content value="tab1">Press Enter to switch tabs.</ui:tabs.content>
    <ui:tabs.content value="tab2">Content for tab 2.</ui:tabs.content>
    <ui:tabs.content value="tab3">Content for tab 3.</ui:tabs.content>
</ui:tabs.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

tabs.root

Provides shared tabs state and wraps the tab list and panels. Renders a <div> element.

Name	Description	Required	Default
`loopFocus`	`boolean` Whether the keyboard navigation will loop from last tab to first, and vice versa.	No	true
`defaultValue`	`string` The initial selected tab value when rendered. Use when you don't need to control the selected tab value.	No	-
`orientation`	`Enum\Orientation` The orientation of the tabs.	No	Horizontal
`activationMode`	`Enum\TabsActivationMode` The activation mode of the tabs.	No	Automatic
`virtualFocus`	`boolean` Whether the tabs use virtual focus instead of a roving tabindex. Triggers then receive no DOM focus: arrow keys only move the focused value and every trigger and panel stays out of the tab order. Useful when the tabs live inside another widget that manages focus, like a combobox.	No	false
`deselectable`	`boolean` Whether the active tab can be deselected when clicking on it.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tabs-root`	<uid>
`data-orientation`	The orientation of the tabs
`data-focus`	Present when focused

tabs.list

Groups the tab triggers. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tabs-list`	<uid>
`data-focus`	Present when focused
`data-orientation`	The orientation of the list

tabs.trigger

Activates a tab and focuses its panel. Renders a <button> element.

Name	Description	Required	Default
`value`	`string` The value of the tab.	Yes	-
`disabled`	`boolean` Whether the tab is disabled.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tabs-trigger`	<uid>
`data-orientation`	The orientation of the trigger
`data-disabled`	Present when disabled
`data-value`	The value of the item
`data-selected`	Present when selected
`data-focus`	Present when focused
`data-ssr`	Present when not rendered in the browser. Useful for ssr styling

tabs.indicator

Displays the active tab indicator. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tabs-indicator`	<uid>
`data-orientation`	The orientation of the indicator

tabs.content

Displays the panel content for a tab. Renders a <div> element.

Name	Description	Required	Default
`value`	`string` The value of the tab.	Yes	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tabs-content`	<uid>
`data-selected`	Present when selected
`data-orientation`	The orientation of the content

Machine JavaScript API

Name	Type	Description
`value`	`string \| null`	The current value of the tabs.
`focusedValue`	`string \| null`	The value of the tab that is currently focused.
`setValue`	`(value: string) => void`	Sets the value of the tabs.
`clearValue`	`VoidFunction`	Clears the value of the tabs.
`setIndicatorRect`	`(value: string) => void`	Sets the indicator rect to the tab with the given value
`syncTabIndex`	`VoidFunction`	Synchronizes the tab index of the content element. Useful when rendering tabs within a select or combobox
`focus`	`VoidFunction`	Set focus on the selected tab trigger
`selectNext`	`(fromValue?: string) => void`	Selects the next tab
`selectPrev`	`(fromValue?: string) => void`	Selects the previous tab
`getTriggerState`	`(props: TriggerProps) => TriggerState`	Returns the state of the trigger with the given props
`getContentState`	`(props: ContentProps) => ContentState`	Returns the state of the content with the given props

Accessibility

Key	Description
`Tab`	When focus moves onto the tabs, focuses the active trigger. When a trigger is focused, moves focus to the active content.
`ArrowDown`	Moves focus to the next trigger in vertical orientation and activates its associated content.
`ArrowRight`	Moves focus to the next trigger in horizontal orientation and activates its associated content.
`ArrowUp`	Moves focus to the previous trigger in vertical orientation and activates its associated content.
`ArrowLeft`	Moves focus to the previous trigger in horizontal orientation and activates its associated content.
`Home`	Moves focus to the first trigger and activates its associated content.
`End`	Moves focus to the last trigger and activates its associated content.
`EnterSpace`	In manual mode, when a trigger is focused, moves focus to its associated content.

Tabs

Features

Anatomy

Installation

Examples

Vertical Orientation

Disabled Tabs

Manual Activation

API Reference

tabs.root

Rendered data attributes

tabs.list

Rendered data attributes

tabs.trigger

Rendered data attributes

tabs.indicator

Rendered data attributes

tabs.content

Rendered data attributes

Machine JavaScript API

Accessibility

On this page