Tabs
A component for toggling between related panels on the same page.
Manage your account settings and preferences.
Change your password and other security options.
Configure your application 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>
import { mount } from 'fluid-primitives';
import { Tabs } from 'fluid-primitives/tabs';
mount('tabs', ({ props }) => {
const tabs = new Tabs(props);
tabs.init();
return tabs;
});
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
Installation
typo3 ui:add tabs
Please copy the files manually from GitHub into your project.
Read more about installing Components and Primitives.
Examples
Vertical Orientation
Display tabs in a vertical layout.
Manage your account settings and preferences.
Change your password and other security options.
Configure your application 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.
This tab is disabled.
Third 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.
Content for tab 2.
Content for tab 3.
<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 | booleanWhether the keyboard navigation will loop from last tab to first, and vice versa. | No | true |
defaultValue | stringThe initial selected tab value when rendered. Use when you don't need to control the selected tab value. | No | - |
orientation | Enum\OrientationThe orientation of the tabs. | No | Horizontal |
activationMode | Enum\TabsActivationModeThe activation mode of the tabs. | No | Automatic |
composite | booleanWhether the tab is composite. | No | true |
deselectable | booleanWhether the active tab can be deselected when clicking on it. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-scope | tabs |
data-part | root |
data-orientation | The orientation of the tabs |
data-focus | Present when focused |
tabs.list
Groups the tab triggers. Renders a <div> element.
Rendered data attributes
| Attribute | Description |
|---|---|
data-scope | tabs |
data-part | list |
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 | stringThe value of the tab. | Yes | - |
disabled | booleanWhether the tab is disabled. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-scope | tabs |
data-part | trigger |
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.
Rendered data attributes
| Attribute | Description |
|---|---|
data-scope | tabs |
data-part | indicator |
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 | stringThe value of the tab. | Yes | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-scope | tabs |
data-part | content |
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 |
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. |
Anatomy
<primitives:tabs.root>
<primitives:tabs.list>
<primitives:tabs.trigger />
<primitives:tabs.indicator />
</primitives:tabs.list>
<primitives:tabs.content />
</primitives:tabs.root>