Tabs
Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support.
To get started, install Headless UI via npm:
npm install @headlessui/vue
Tabs are built using the TabGroup
, TabList
, Tab
, TabPanels
, and TabPanel
components. By default the first tab is selected, and clicking on any tab or selecting it with the keyboard will activate the corresponding panel.
<template> <TabGroup> <TabList> <Tab>Tab 1</Tab> <Tab>Tab 2</Tab> <Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue' </script>
This is a headless component so there are no styles included by default. Instead, the components expose useful information via scoped slots that you can use to apply styles yourself.
To style the selected Tab
, use the selected
slot prop, which tells you whether or not that tab is currently selected.
<template> <TabGroup> <TabList>
<Tab v-slot="{ selected }" as="template"><button:class="[selected ? 'bg-blue-500 text-white' : 'bg-white text-black']"> Tab 1 </button> </Tab> <Tab>Tab 2</Tab> <Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue' </script>
To disable a tab, use the disabled
prop on the Tab
component. Disabled tabs cannot be selected with the mouse, and are also skipped when navigating the tab list using the keyboard.
<template> <TabGroup> <TabList> <Tab>Tab 1</Tab>
<Tab disabled>Tab 2</Tab><Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue' </script>
By default, tabs are automatically selected as the user navigates through them using the arrow keys.
If you'd rather not change the current tab until the user presses Enter
or Space
, use the manual
prop on the TabGroup
component. This can be helpful if selecting a tab performs an expensive operation and you don't want to run it unnecessarily.
<template>
<TabGroup manual><TabList> <Tab>Tab 1</Tab> <Tab>Tab 2</Tab> <Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue' </script>
The manual
prop has no impact on mouse interactions — tabs will still be selected as soon as they are clicked.
If you've styled your TabList
to appear vertically, use the vertical
prop to enable navigating with the up and down arrow keys instead of left and right, and to update the aria-orientation
attribute for assistive technologies.
<template>
<TabGroup vertical><TabList> <Tab>Tab 1</Tab> <Tab>Tab 2</Tab> <Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue' </script>
To change which tab is selected by default, use the :defaultIndex="number"
prop on the TabGroup
component.
<template>
<TabGroup :defaultIndex="1"><TabList> <Tab>Tab 1</Tab><!-- Selects this tab by default --><Tab>Tab 2</Tab><Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel><!-- Displays this tab by default --><TabPanel>Content 2</TabPanel><TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue' </script>
If you happen to provide an index that is out of bounds, then the last non-disabled tab will be selected on initial render. (For example, <TabGroup :defaultIndex="5"
in the example above would render the third panel as selected.)
To run a function whenever the selected tab changes, use the @change
event on the TabGroup
component.
<template>
<TabGroup @change="changeTab"><TabList> <Tab>Tab 1</Tab> <Tab>Tab 2</Tab> <Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'function changeTab(index) {console.log('Changed active tab to:', index)}</script>
The tabs component can also be used as a controlled component. To do this, provide the selectedIndex
and manage the state yourself.
<template>
<TabGroup :selectedIndex="selectedTab" @change="changeTab"><TabList> <Tab>Tab 1</Tab> <Tab>Tab 2</Tab> <Tab>Tab 3</Tab> </TabList> <TabPanels> <TabPanel>Content 1</TabPanel> <TabPanel>Content 2</TabPanel> <TabPanel>Content 3</TabPanel> </TabPanels> </TabGroup> </template> <script setup> import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'const selectedTab = ref(0)function changeTab(index) {selectedTab.value = index}</script>
Clicking a Tab
will select that tab and display the corresponding TabPanel
.
All interactions apply when a Tab
component is focused.
Command | Description |
ArrowLeft and ArrowRight | Selects the previous/next non-disabled tab. |
ArrowUp and ArrowDownwhen | Selects the previous/next non-disabled tab. |
Home or PageUp | Selects the first non-disabled tab. |
End or PageDown | Selects the last non-disabled tab. |
Enter or Space when | Activates the selected tab. |
All relevant ARIA attributes are automatically managed.
For a full reference on all accessibility features implemented in Tabs
, see the ARIA spec on Tabs.
The main TabGroup component.
Prop | Default | Description |
as | template | String | Component The element or component the |
defaultIndex | 0 | Number The default selected index |
selectedIndex | — | number The selected index if you want to use the Tabs component as a controlled component. |
vertical | false | Boolean When true, the orientation of the |
manual | false | Boolean When true, the user can only display a panel via the keyboard by first navigating to it using the arrow keys, and then by pressing |
Slot Prop | Description |
selectedIndex |
The currently selected index. |
Event | Description |
change | A function called whenever the active tab changes. |
Prop | Default | Description |
as | div | String | Component The element or component the |
Slot Prop | Description |
selectedIndex |
The currently selected index. |
Prop | Default | Description |
as | button | String | Component The element or component the |
disabled | false | Boolean Whether or not the |
Slot Prop | Description |
selected |
Whether or not the |
Prop | Default | Description |
as | div | String | Component The element or component the |
Slot Prop | Description |
selectedIndex |
The currently selected index. |
Prop | Default | Description |
as | div | String | Component The element or component the |
Slot Prop | Description |
selected |
Whether or not the |
If you're interested in predesigned component examples using Headless UI and Tailwind CSS, check out Tailwind UI — a collection of beautifully designed and expertly crafted components built by us.
It's a great way to support our work on open-source projects like this and makes it possible for us to improve them and keep them well-maintained.