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.

Organizational tabs

Preview

Controlled

Tab 2

Content for tab 2

Uncontrolled

Tab 2

Content for tab 2

Code

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

Controlled

• Tab 1
• Tab 2
• Tab 3

Uncontrolled

• Tab 1
• Tab 2
• Tab 3

Code

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 Ref<HTMLDivElement>

The ref type for this component.

TabsProps

children * ReactNode

The children of the <Tabs> element. Should include <TabList> and <TabPanels> elements.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

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 CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-label string

Defines a string value that labels the current element.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

disabledKeys Iterable<Key, any, any>

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

selectedKey null | Key

The currently selected key in the collection (controlled).

defaultSelectedKey Key

The initial selected key in the collection (uncontrolled).

onSelectionChange (key: Key) => void

Handler that is called when the selection changes.

StyleProps

margin Responsive<Spacing | "auto">

The amount of margin applied to all edges of this component.

marginX Responsive<Spacing | "auto">

The amount of margin applied to the left and right edges of this component. Takes priority over margin.

marginY Responsive<Spacing | "auto">

The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.

marginTop Responsive<Spacing | "auto">

The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.

marginRight Responsive<Spacing | "auto">

The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.

marginBottom Responsive<Spacing | "auto">

The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.

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 ReactNode | ((item: T) => ReactNode)

The contents of the collection.

items Iterable<T, any, any>

The items to display in the collection.

Tab

Renders a single tab within TabList.

TabProps

children * StringLikeChildren

The text to display as the tab title.

iconStart ReactNode

An icon displayed before the tab title.

badge ReactNode

A badge displayed after the tab title.

onHoverStart (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

id Key

The unique id of the tab.

isDisabled boolean

Whether the tab is disabled.

TabPanels

Renders a collection of TabPanel components within Tabs.

TabPanelsProps<T extends CollectionItem>

children ReactNode | ((item: T) => ReactNode)

The contents of the collection.

items Iterable<T, any, any>

The items to display in the collection.

TabPanel

Renders a single tab panel within TabPanels.

TabPanelProps

children * ReactNode

The content to display in the tab panel.

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 Ref<HTMLDivElement>

The ref type for this component.

LinkTabsProps

children * ReactNode

Link tabs belonging to the group.

isDisabled boolean

Whether the link tabs are disabled.

currentHref null | string

The currently selected key in the collection (controlled).

defaultHref null | string

The initial selected key in the collection (uncontrolled).

onHrefChange (href: null | string) => void

Handler that is called when the selection changes.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

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 CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-label string

Defines a string value that labels the current element.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

StyleProps

margin Responsive<Spacing | "auto">

The amount of margin applied to all edges of this component.

marginX Responsive<Spacing | "auto">

The amount of margin applied to the left and right edges of this component. Takes priority over margin.

marginY Responsive<Spacing | "auto">

The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.

marginTop Responsive<Spacing | "auto">

The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.

marginRight Responsive<Spacing | "auto">

The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.

marginBottom Responsive<Spacing | "auto">

The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.

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 * StringLikeChildren

The text to display as the tab title.

href * string

A URL to link to.

iconStart ReactNode

An icon displayed before the tab title.

badge ReactNode

A badge displayed after the tab title.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

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 CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

routerOptions undefined

Options for the configured client side router.

isDisabled boolean

Whether the link is disabled.

hrefLang string

Hints at the human language of the linked URL. SeeMDN.

target HTMLAttributeAnchorTarget

The target window for the link. See MDN.

rel string

The relationship between the linked resource and the current page. See MDN.

download string | boolean

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping string

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy HTMLAttributeReferrerPolicy

How much of the referrer to send when following the link. See MDN.

onHoverStart (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd (e: HoverEvent) => void

Handler that is called when a hover interaction ends.