TabPanel

Renders a tab panel element that's controlled by a Tab component.

If the tabId prop isn't provided, the tab panel will automatically associate with a Tab based on its position in the DOM. Alternatively, you can render a single tab panel with a dynamic tabId value pointing to the selected tab.

Code examples

<TabProvider>
  <TabList>
    <Tab>Tab 1</Tab>
    <Tab>Tab 2</Tab>
  </TabList>
  <TabPanel>Panel 1</TabPanel>
  <TabPanel>Panel 2</TabPanel>
</TabProvider>
<TabProvider>
  <TabList>
    <Tab>Tab 1</Tab>
    <Tab>Tab 2</Tab>
  </TabList>
  <TabPanel>Panel 1</TabPanel>
  <TabPanel>Panel 2</TabPanel>
</TabProvider>

Optional Props

`accessibleWhenDisabled`

boolean | undefined
boolean | undefined

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls⁠.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

`alwaysVisible`

boolean | undefined = false
boolean | undefined = false

Determines whether the content element should remain visible even when the open state is false. If this prop is set to true, the hidden prop and the display: none style will not be applied, unless explicitly set otherwise.

This prop is particularly useful when using third-party animation libraries such as Framer Motion or React Spring, where the element needs to be visible for exit animations to work.

Live examples

Dialog with Framer MotionUsing Framer Motion to add initial and exit animations to a modal Dialog and its backdrop element.

Menu with Framer MotionAbstracting Menu into a reusable dropdown menu component that uses Framer Motion to create smooth initial and exit animations.

Tooltip with Framer MotionAbstracting Tooltip into a reusable custom component that uses Framer Motion to create smooth initial and exit animations.

Dialog with details & summaryCombining Dialog with the native details element in React so users can interact with it before JavaScript finishes loading.

`autoFocus`

boolean | undefined = false
boolean | undefined = false

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Dialog with React RouterUsing React Router to create a modal Dialog that's controlled by the browser history.

Nested DialogRendering a modal Dialog to confirm an action inside another modal dialog using React.

`disabled`

boolean | undefined = false
boolean | undefined = false

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don't support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

SubmenuRendering nested Menu components to create a dropdown menu with submenus that open when hovering over the parent menu item.

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Context menuShowing Menu when right-clicking on an element using the getAnchorRect prop to determine the position of the popover.

`focusable`

boolean | undefined = true
boolean | undefined = true

Determines if Focusable features should be active on non-native focusable elements.

Note: This prop only turns off the additional features provided by the Focusable component. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability, but without added features such as improved autoFocus, accessibleWhenDisabled, onFocusVisible, etc.

`getItem`

((props: CollectionStoreItem) => CollectionStoreItem) | undefined
((props: CollectionStoreItem) => CollectionStoreItem) | undefined

A memoized function that returns props to be passed with the item during its registration in the store.

Code examples

const getItem = useCallback((data) => ({ ...data, custom: true }), []);
<CollectionItem getItem={getItem} />
const getItem = useCallback((data) => ({ ...data, custom: true }), []);
<CollectionItem getItem={getItem} />

`id`

string | undefined
string | undefined

The unique ID of the item. This will be used to register the item in the store and for the element's id attribute. If not provided, a unique ID will be automatically generated.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Tab with React RouterUsing React Router to create Tab links and tab panels controlled by the browser history, while maintaining keyboard navigation.

Animated TabPanelUsing plain CSS transitions to slide in and out TabPanel components as they are expanded.

Select with Combobox and TabsAbstracting Select to work alongside Combobox and Tab components, presenting a searchable, tabbed dropdown.

`onFocusVisible`

BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined
BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined

Custom event handler invoked when the element gains focus through keyboard interaction or a key press occurs while the element is in focus. This is the programmatic equivalent of the data-focus-visible attribute.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Custom CheckboxRendering a visually hidden Checkbox using the VisuallyHidden component to show a custom checkbox presentation in React.

`render`

RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined
RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

`scrollElement`

HTMLElement | React.RefObject<HTMLElement> | ((panel: HTMLElement) => HTMLElement | null) | undefined
HTMLElement | React.RefObject<HTMLElement> | ((panel: HTMLElement) => HTMLElement | null) | undefined

When using the scrollRestoration prop, the tab panel element serves as the default scroll element. You can use this prop to designate a different element for scrolling.

If a function is provided, it will be called with the tab panel element as an argument. The function should return the element to scroll.

Code examples

<TabPanel
  scrollRestoration
  scrollElement={(panel) => panel.querySelector(".scrollable")}
/>
<TabPanel
  scrollRestoration
  scrollElement={(panel) => panel.querySelector(".scrollable")}
/>

`scrollRestoration`

boolean | "reset" | undefined = false
boolean | "reset" | undefined = false

Manages the scrolling behavior of the tab panel when it is hidden and then shown again.

This is especially useful when using a single tab panel for multiple tabs, where you dynamically change the tabId prop and the panel's children, which would otherwise retain the current scroll position when switching tabs.

When set to true, the component will save the scroll position and restore it when the panel is shown again. When set to "reset", the scroll position will reset to the top when the panel is displayed again.

The default scroll element is the tab panel itself. To scroll a different element, use the scrollElement prop.

`shouldRegisterItem`

boolean | undefined = true
boolean | undefined = true

Whether the item should be registered as part of the collection.

`store`

TabStore | undefined
TabStore | undefined

Object returned by the useTabStore hook. If not provided, the closest TabProvider component's context will be used.

`tabId`

string | null | undefined
string | null | undefined

The id of the tab controlling this panel. This connection is used to assign the aria-labelledby attribute to the tab panel and to determine if the tab panel should be visible.

This link is automatically established by matching the order of Tab and TabPanel elements in the DOM. If you're rendering a single tab panel, this can be set to a dynamic value that refers to the selected tab.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Tab with React RouterUsing React Router to create Tab links and tab panels controlled by the browser history, while maintaining keyboard navigation.

Animated TabPanelUsing plain CSS transitions to slide in and out TabPanel components as they are expanded.

Select with Combobox and TabsAbstracting Select to work alongside Combobox and Tab components, presenting a searchable, tabbed dropdown.

`unmountOnHide`

boolean | undefined = false
boolean | undefined = false

When set to true, the content element will be unmounted and removed from the DOM when it's hidden.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.

Textarea with inline ComboboxRendering Combobox as a textarea element to create an accessible multiline textbox in React. Inserting specific characters triggers a popup with dynamic suggestions.

Standalone PopoverAbstracting the Popover component so that it can be used without PopoverDisclosure or PopoverAnchor. This example uses the getAnchorRect prop to determine the position of the popup.

Animated SelectAnimating Select using CSS transitions in React. The component waits for the transition to finish before completely hiding the popover.

Multi-SelectAllowing the Select component to select multiple values by passing an array to the defaultValue prop on the SelectProvider component.

TabPanel

Live examples

Live examples

Live examples

Live examples

Code examples

Live examples

Live examples

Code examples

Live examples

Live examples

Stay tuned