DISCLAIMER: This component is in

Beta

status. That means that it is ready for production, but the API might change.

Tabs

Explore and switch between different views using tabs

Danish Composers

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  return (
    <>
      <div class="tabs-example">
        <h3>Danish Composers</h3>
        <Tabs behavior="automatic">
          <TabList>
            <Tab>Maria</Tab>
            <Tab>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
      </div>
    </>
  );
});

Building blocks

The full version

import { component$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';

export default component$(() => {
  return (
    <Tabs selectedIndex={1}>
      <TabList>
        <Tab>Tab 1</Tab>
        <Tab>Tab 2</Tab>
        <Tab>Tab 3</Tab>
      </TabList>

      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </Tabs>
  );
});

The short version

import { component$ } from '@builder.io/qwik';
import { TabPanel, Tabs } from '@qwik-ui/headless';

export default component$(() => {
  return (
    <Tabs>
      <TabPanel title="Tab 1">Content 1</TabPanel>
      <TabPanel title="Tab 2" selected>
        Content 2
      </TabPanel>
      <TabPanel title="Tab 3">Content 3</TabPanel>
    </Tabs>
  );
});

Vertical

by default, the tabs are horizontal, but you can adjust the underlying behavior to be vertical by setting the vertical prop to true.

Danish Composers

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>

        <Tabs vertical class="flex flex-wrap gap-5">
          <TabList class="flex w-fit flex-col">
            <Tab>Maria</Tab>
            <Tab>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
      </div>
    </>
  );
});

Disabled

You can disable a tab by setting the disabled prop to true.

Dad jokes

"What's brown and sticky", " A stick."

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  return (
    <>
      <div class="tabs-example mr-auto w-full">
        <h3>Dad jokes</h3>
        <Tabs>
          <TabList>
            <Tab
              style={{ width: '125px' }}
              class="aria-disabled:cursor-not-allowed"
              disabled={true}
            >
              Disabled Tab
            </Tab>
            <Tab style={{ width: '125px' }}>Joke 2</Tab>
            <Tab style={{ width: '125px' }}>Joke 3</Tab>
            <Tab style={{ width: '125px' }}>Joke 4</Tab>
          </TabList>
          <TabPanel>"What did the coffee report to the police", " A mugging."</TabPanel>
          <TabPanel>"What's brown and sticky", " A stick."</TabPanel>
          <TabPanel>"How do the trees get on the internet?", "They log on."</TabPanel>
          <TabPanel>"What did the fish say when he hit the wall", " Dam."</TabPanel>
        </Tabs>
      </div>
    </>
  );
});

Behavior

Automatic

The default behavior of the tabs is manual, which means that the tabs will automatically switch to the next tab when the user hovers over the tab. You can change this behavior by setting the behavior prop to automatic.

Danish Composers

(Hover over the tabs)

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>
        <h4>(Hover over the tabs)</h4>
        <Tabs behavior="automatic">
          <TabList>
            <Tab>Maria</Tab>
            <Tab>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
      </div>
    </>
  );
});

Manual

You can set the behavior to manual, which means that the tabs will not automatically switch to the next tab when the user presses the right arrow key, and to the previous tab when the user presses the left arrow key.

Danish Composers

(Hover over the tabs - they should not be selected)

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>
        <h4 class="mb-4">(Hover over the tabs - they should not be selected)</h4>
        <Tabs behavior="manual">
          <TabList>
            <Tab>Maria</Tab>
            <Tab>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
      </div>
    </>
  );
});

Dynamic

Dynamic Tab 1 Panel

import { component$, useStore, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  const tabsState = useStore(['Dynamic Tab 1', 'Dynamic Tab 2', 'Dynamic Tab 3']);
  return (
    <>
      <div class="tabs-example mr-auto">
        <Tabs>
          <TabList>
            {tabsState.map((tab) => (
              <Tab key={tab}>{tab}</Tab>
            ))}
          </TabList>
          {tabsState.map((tab) => (
            <TabPanel key={tab}>{tab} Panel</TabPanel>
          ))}
        </Tabs>

        <button
          class="mt-4 font-bold text-red-600"
          onClick$={() => {
            if (tabsState.length > 1) {
              tabsState.splice(0, 1);
            }
          }}
        >
          Remove First Tab
        </button>
      </div>
    </>
  );
});

onSelectedIndexChange$

You can listen to changes in the selected index by subscribing to the onSelectedIndexChange$ store.

Danish Composers

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

Selected Index: 0

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  const selectedIndexSig = useSignal(0);
  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>
        <Tabs
          onSelectedIndexChange$={(index) => {
            selectedIndexSig.value = index;
          }}
        >
          <TabList>
            <Tab>Maria</Tab>
            <Tab>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>

        <p class="mt-4 text-white">Selected Index: {selectedIndexSig.value}</p>
      </div>
    </>
  );
});

bind:selectedIndex

You can provide a signal for the selected index with the bind:selectedIndex={yourSignal} and it will be used directly. This is a more efficient version of onSelectedIndexChange$.

bind:selectedTabId

You can provide a signal for the selected tab id with the bind:selectedTabId={yourSignal} and it will be used directly.

💡 You can manually set the tabId prop on each tab to be able to select any tab by its ID.

Danish Composers

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

Selected Tab Id: Maria

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  const selectedTabIdSig = useSignal<string | undefined>();
  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>
        <Tabs bind:selectedTabId={selectedTabIdSig}>
          <TabList>
            <Tab tabId="Maria">Maria</Tab>
            <Tab tabId="Carl">Carl</Tab>
            <Tab tabId="Ida">Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
        <p class="mt-4 text-white">
          <strong>Selected Tab Id</strong>: {selectedTabIdSig.value}
        </p>
      </div>
    </>
  );
});

Add a "selected" prop

You can add a "selected" prop to the Tab component to make it selected by default.

Danish Composers

Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>

        <Tabs>
          <TabList>
            <Tab>Maria</Tab>
            <Tab selected>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
      </div>
    </>
  );
});

onClick$

You can pass a custom onClick$ handler.

Danish Composers

(Hover over the tabs - they should not be selected)

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

import { component$, useStyles$ } from '@builder.io/qwik';
import { Tab, TabList, TabPanel, Tabs } from '@qwik-ui/headless';
import styles from '.././index.css?inline';

export default component$(() => {
  useStyles$(styles);
  return (
    <>
      <div class="tabs-example mr-auto">
        <h3>Danish Composers</h3>
        <h4 class="mb-4">(Hover over the tabs - they should not be selected)</h4>
        <Tabs behavior="manual">
          <TabList>
            <Tab>Maria</Tab>
            <Tab>Carl</Tab>
            <Tab>Ida</Tab>
          </TabList>
          <TabPanel>
            <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
          </TabPanel>
          <TabPanel>
            <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
          </TabPanel>
        </Tabs>
      </div>
    </>
  );
});

Creating reusable Tabs

In order to remove the need for a linking value prop for each Tab and TabPanel pair, we have chosen to create the Tabs component as an inline component.

By consequence, the Tabs component needs to be aware of its children. If you want to create your custom reusable TabList/Tab/TabPanel components, you will have to pass them to the Tabs component through its TabList, Tab, and TabPanel props:

const CustomTabs = (props: TabsProps) => (
  <Tabs
    {...props}
    tabListComponent={CustomTabList}
    tabComponent={CustomTab}
    tabPanelComponent={CustomTabPanel}
  />
);

Description:

Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...

import { Slot, component$ } from '@builder.io/qwik';
import {
  Tab,
  TabList,
  TabListProps,
  TabPanel,
  TabPanelProps,
  TabProps,
  Tabs,
  TabsProps,
} from '@qwik-ui/headless';

const CustomTabs = (props: TabsProps) => (
  <Tabs
    {...props}
    tabListComponent={CustomTabList}
    tabComponent={CustomTab}
    tabPanelComponent={CustomTabPanel}
  />
);

const CustomTabList = component$<TabListProps>(() => {
  return (
    <TabList>
      <Slot />
    </TabList>
  );
});

const CustomTab = component$<TabProps>(({ ...props }) => {
  return (
    <Tab {...props}>
      <span class="text-red-500">Custom</span>
      <Slot />
    </Tab>
  );
});

const CustomTabPanel = component$<TabPanelProps>(({ ...props }) => {
  return (
    <TabPanel {...props}>
      <span class="text-red-500">Description:</span>
      <Slot />
    </TabPanel>
  );
});

export default component$(() => {
  return (
    <div class="tabs-example mr-auto">
      <CustomTabs>
        <CustomTabList>
          <CustomTab>Tab 1</CustomTab>
          <CustomTab>Tab 2</CustomTab>
          <CustomTab>Tab 3</CustomTab>
        </CustomTabList>
        <CustomTabPanel>
          <p>Maria Theresia Ahlefeldt (16 January 1755 - 20 December 1810) ...</p>
        </CustomTabPanel>
        <CustomTabPanel>
          <p>Carl Joachim Andersen (29 April 1847 - 7 May 1909) ...</p>
        </CustomTabPanel>
        <CustomTabPanel>
          <p>Ida Henriette da Fonseca (July 27, 1802 - July 6, 1858) ...</p>
        </CustomTabPanel>
      </CustomTabs>
    </div>
  );
});

Accessibility

Keyboard interaction

Key	Description
`Tab`	Moves focus to the selected panel.
`Shift + Tab`	Moves focus to the selected tab.
`ArrowRight`	Moves focus to the next tab.
`ArrowLeft`	Moves focus to the previous tab.
`ArrowDown`	In "vertical mode", moves focus to the next tab.
`ArrowUp`	In "vertical mode", moves focus to the previous tab.
`Home`	Moves focus to the first tab.
`PageUp`	Moves focus to the first tab.
`End`	Moves focus to the last tab.
`PageDown`	Moves focus to the first tab.

API

Tabs

Prop	Type	Description
`behavior`	`string`	Toggle between automatic or manual. The automatic behavior moves between tabs when hover. The manual behavior moves between tabs on click.
`selectedIndex`	`number`	A way to set the selected index programmatically
`selectedTabId`	`number`	A way to set the selected tabId programmatically. The tabId is set by the `key` prop of the Tab or TabPanel
`vertical`	`boolean`	If set to true, the behavior of UpArrow and DownArrow will navigate between tabs vertically instead of horizontally.
`onSelectedIndexChange$`	`function`	An event hook that gets notified whenever the selected index changes
`onSelectedTabIdChange$`	`function`	An event hook that gets notified whenever the selected tabId changes
`bind:selectedIndex`	`signal`	A signal that binds the selected index. This is a more efficient version of `selectedIndex` + `onSelectedIndexChange$`
`bind:selectedTabId`	`signal`	A signal that binds the selected tabId. This is a more efficient version of `selectedTabId` + `onSelectedTabIdChange$`
`tabClass`	`string`	The class name to apply to tabs
`panelClass`	`string`	The class name to apply to panels

Tab

Prop	Type	Description
`selectedClassName`	`string`	The class name to apply when the tab is selected
`selected`	`boolean`	Select this tab by default
`disabled`	`boolean`	Set the disabled state of a specific tab
`tabId`	`string`	Set the tab id, can be used with `bind:selectedTabId` to select a tab programmatically

TabPanel

Prop	Type	Description
`label`	`element`	Shorthand for `<Tab>{label}</Tab>`
`selected`	`boolean`	Select this tab by default