Tabs API

Import

Cimpress UI exports four tabs-related components:

Tabs: container component that displays a list of organizational tabs.
TabList: renders a list of tabs within Tabs.
Tab: renders a single tab within Tabs.
TabPanels: renders a list of tab panels within Tabs.
TabPanel: renders a single tab panel within Tabs.
LinkTabs: container component that displays a list of navigational tabs.
LinkTab: renders a single tab within LinkTabs.

import { Tabs, TabList, Tab, TabPanels, TabPanel, LinkTabs, LinkTab } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Controlled

Tab 1

Tab 2

Tab 3

Content for tab 2

Uncontrolled

Tab 1

Tab 2

Tab 3

Content for tab 2

import { type Key, Stack, Tabs, Tab, TabList, TabPanel, TabPanels, Text } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [selectedKey, setSelectedKey] = useState<Key | null>('tab-2');

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Controlled
        </Text>

        <Tabs aria-label="Tabs example (controlled)" selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
          <TabList>
            <Tab id="tab-1">Tab 1</Tab>
            <Tab id="tab-2">Tab 2</Tab>
            <Tab id="tab-3">Tab 3</Tab>
          </TabList>
          <TabPanels>
            <TabPanel id="tab-1">Content for tab 1</TabPanel>
            <TabPanel id="tab-2">Content for tab 2</TabPanel>
            <TabPanel id="tab-3">Content for tab 3</TabPanel>
          </TabPanels>
        </Tabs>
      </Stack>

      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Uncontrolled
        </Text>

        <Tabs aria-label="Tabs example (uncontrolled)" defaultSelectedKey="tab-2">
          <TabList>
            <Tab id="tab-1">Tab 1</Tab>
            <Tab id="tab-2">Tab 2</Tab>
            <Tab id="tab-3">Tab 3</Tab>
          </TabList>
          <TabPanels>
            <TabPanel id="tab-1">Content for tab 1</TabPanel>
            <TabPanel id="tab-2">Content for tab 2</TabPanel>
            <TabPanel id="tab-3">Content for tab 3</TabPanel>
          </TabPanels>
        </Tabs>
      </Stack>
    </Stack>
  );
}

Navigational tabs

Preview
Code

Controlled

Uncontrolled

import { type Href, LinkTabs, LinkTab, Stack, Text } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [currentHref, setCurrentHref] = useState<Href | null>('#tab-2');

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Controlled
        </Text>

        <LinkTabs aria-label="Link tabs example (controlled)" currentHref={currentHref} onHrefChange={setCurrentHref}>
          <LinkTab href="#tab-1">Tab 1</LinkTab>
          <LinkTab href="#tab-2">Tab 2</LinkTab>
          <LinkTab href="#tab-3">Tab 3</LinkTab>
        </LinkTabs>
      </Stack>

      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Uncontrolled
        </Text>

        <LinkTabs aria-label="Link tabs example (uncontrolled)" defaultHref="#tab-2">
          <LinkTab href="#tab-1">Tab 1</LinkTab>
          <LinkTab href="#tab-2">Tab 2</LinkTab>
          <LinkTab href="#tab-3">Tab 3</LinkTab>
        </LinkTabs>
      </Stack>
    </Stack>
  );
}

Accessibility notes

Tabs follows the ARIA tabs pattern. See the linked page for a list of available keyboard interactions.

The Tabs tab list is a single tab stop within the page’s tab order. Use the Tab key to navigate to the list, and the arrow keys to navigate between tabs within the list.

Tab can be activated by pressing Enter or Space, similar to a native HTML button.

LinkTab can be activated by pressing Enter, similar to a native HTML link.

Tabs should have an aria-label prop defined to identify the purpose of the tabs to assistive technologies. See our accessibility guide for more details.

LinkTabs renders a navigation landmark, and requires a textual label to identify itself to assistive technologies. See our accessibility guide for more details.

Collections

Tabs is a collection component. See our collection components guide to learn how to work with collections.

API reference

Tabs

Organizes content into multiple sections that users can switch between.

See tabs usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

TabsProps

children * Section titled “ children * ” ReactNode: The children of the <Tabs> element. Should include <TabList> and <TabPanels> elements.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
disabledKeys Section titled “ disabledKeys ” Iterable<Key, any, any>: The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
selectedKey Section titled “ selectedKey ” Key | null: The currently selected key in the collection (controlled).
defaultSelectedKey Section titled “ defaultSelectedKey ” Key: The initial selected key in the collection (uncontrolled).
onSelectionChange Section titled “ onSelectionChange ” (key: Key) => void: Handler that is called when the selection changes.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

TabList

Renders a collection of Tab components within Tabs.

TabListProps<T extends CollectionItem>

children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Section titled “ items ” Iterable<T, any, any>: The items to display in the collection.

Tab

Renders a single tab within TabList.

TabProps

children * Section titled “ children * ” StringLikeChildren: The text to display as the tab title.
id Section titled “ id ” Key: The unique ID of the tab.
iconStart Section titled “ iconStart ” ReactNode: An icon displayed before the tab title.
badge Section titled “ badge ” ReactNode: A badge displayed after the tab title.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
isDisabled Section titled “ isDisabled ” boolean: Whether the tab is disabled.

TabPanels

Renders a collection of TabPanel components within Tabs.

TabPanelsProps<T extends CollectionItem>

children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Section titled “ items ” Iterable<T, any, any>: The items to display in the collection.

TabPanel

Renders a single tab panel within TabPanels.

TabPanelProps

children * Section titled “ children * ” ReactNode: The content to display in the tab panel.
id Section titled “ id ” Key: The unique id of the associated tab.

LinkTabs

Displays a list of tabs to help users navigate through a website.

See tabs usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

LinkTabsProps

children * Section titled “ children * ” ReactNode: Link tabs belonging to the group.
isDisabled Section titled “ isDisabled ” boolean: Whether the link tabs are disabled.
currentHref Section titled “ currentHref ” string | null: The currently selected key in the collection (controlled).
defaultHref Section titled “ defaultHref ” string | null: The initial selected key in the collection (uncontrolled).
onHrefChange Section titled “ onHrefChange ” (href: string | null) => void: Handler that is called when the selection changes.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

LinkTab

Renders a single tab within LinkTabs.

LinkTabProps

children * Section titled “ children * ” StringLikeChildren: The text to display as the tab title.
href * Section titled “ href * ” string: A URL to link to.
iconStart Section titled “ iconStart ” ReactNode: An icon displayed before the tab title.
badge Section titled “ badge ” ReactNode: A badge displayed after the tab title.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
routerOptions Section titled “ routerOptions ” undefined: Options for the configured client side router.
isDisabled Section titled “ isDisabled ” boolean: Whether the link is disabled.
hrefLang Section titled “ hrefLang ” string: Hints at the human language of the linked URL. SeeMDN.
target Section titled “ target ” HTMLAttributeAnchorTarget: The target window for the link. See MDN.
rel Section titled “ rel ” string: The relationship between the linked resource and the current page. See MDN.
download Section titled “ download ” string | boolean: Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
ping Section titled “ ping ” string: A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy Section titled “ referrerPolicy ” HTMLAttributeReferrerPolicy: How much of the referrer to send when following the link. See MDN.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.

Tabs API

Import

Controlled/uncontrolled usage

Organizational tabs

Controlled

Uncontrolled

Navigational tabs

Controlled

Uncontrolled

Accessibility notes

Collections

API reference

Tabs

ref

children *

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

disabledKeys

selectedKey

defaultSelectedKey

onSelectionChange

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

TabList

children

items

Tab

children *

id

iconStart

badge

onHoverStart

onHoverEnd

isDisabled

TabPanels

children

items

TabPanel

children *

id

LinkTabs

ref

children *

isDisabled

currentHref

defaultHref

onHrefChange

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

LinkTab

children *

href *

iconStart

badge

data-cim-style-root

UNSAFE_className