@wordpress/ui: add Tabs

packages/ui/CHANGELOG.md

@@ -2,8 +2,16 @@
 
 ## Unreleased
 
+### New Features
+
+-   Add `Tabs` primitive ([#74652](https://github.com/WordPress/gutenberg/pull/74652)).
+
 ## 0.6.0 (2026-01-29)
 
+### New Features
+
+-   Add `Select` primitive ([#74661](https://github.com/WordPress/gutenberg/pull/74661)).
+
 ## 0.5.0 (2026-01-16)
 
 ### Breaking Changes
@@ -20,4 +28,3 @@
 -   Add `Button` component ([#74415](https://github.com/WordPress/gutenberg/pull/74415), [#74416](https://github.com/WordPress/gutenberg/pull/74416), [#74470](https://github.com/WordPress/gutenberg/pull/74470)).
 -   Add `InputLayout` primitive ([#74313](https://github.com/WordPress/gutenberg/pull/74313)).
 -   Add `Input` primitive ([#74615](https://github.com/WordPress/gutenberg/pull/74615)).
--   Add `Select` primitive ([#74661](https://github.com/WordPress/gutenberg/pull/74661)).

packages/ui/package.json

@@ -45,6 +45,7 @@
 	"dependencies": {
 		"@base-ui/react": "^1.0.0",
 		"@wordpress/a11y": "file:../a11y",
+		"@wordpress/compose": "file:../compose",
 		"@wordpress/element": "file:../element",
 		"@wordpress/i18n": "file:../i18n",
 		"@wordpress/icons": "file:../icons",

packages/ui/src/index.ts

@@ -5,5 +5,6 @@ export * from './form/primitives';
 export * from './icon';
 export * from './icon-button';
 export * from './stack';
+export * as Tabs from './tabs';
 export * as Tooltip from './tooltip';
 export * from './visually-hidden';

packages/ui/src/tabs/index.ts

@@ -0,0 +1,6 @@
+import { List } from './list';
+import { Panel } from './panel';
+import { Root } from './root';
+import { Tab } from './tab';
+
+export { Root, List, Panel, Tab };

packages/ui/src/tabs/list.tsx

@@ -0,0 +1,130 @@
+import { forwardRef, useEffect, useState } from '@wordpress/element';
+import clsx from 'clsx';
+import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import { useMergeRefs } from '@wordpress/compose';
+import styles from './style.module.css';
+import type { TabListProps } from './types';
+
+// Account for sub-pixel rounding errors.
+const SCROLL_EPSILON = 1;
+
+/**
+ * Groups the individual tab buttons.
+ *
+ * `Tabs` is a collection of React components that combine to render
+ * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ */
+export const List = forwardRef< HTMLDivElement, TabListProps >(
+	function TabList(
+		{
+			children,
+			variant = 'default',
+			className,
+			activateOnFocus,
+			render,
+			...otherProps
+		},
+		forwardedRef
+	) {
+		const [ listEl, setListEl ] = useState< HTMLDivElement | null >( null );
+		const [ overflow, setOverflow ] = useState< {
+			first: boolean;
+			last: boolean;
+			isScrolling: boolean;
+		} >( {
+			first: false,
+			last: false,
+			isScrolling: false,
+		} );
+
+		// Check if list is overflowing when it scrolls or resizes.
+		useEffect( () => {
+			if ( ! listEl ) {
+				return;
+			}
+
+			const measureOverflow = () => {
+				const { scrollWidth, clientWidth, scrollLeft } = listEl;
+				const maxScroll = Math.max( scrollWidth - clientWidth, 0 );
+				const direction =
+					listEl.dir ||
+					( typeof window !== 'undefined'
+						? window.getComputedStyle( listEl ).direction
+						: 'ltr' );
+
+				const scrollFromStart =
+					direction === 'rtl' && scrollLeft < 0
+						? // In RTL layouts, scrollLeft is typically 0 at the visual "start"
+						  // (right edge) and becomes negative toward the "end" (left edge).
+						  // Normalize value for correct first/last detection logic.
+						  -scrollLeft
+						: scrollLeft;
+
+				// Use SCROLL_EPSILON to handle subpixel rendering differences.
+				setOverflow( {
+					first: scrollFromStart > SCROLL_EPSILON,
+					last: scrollFromStart < maxScroll - SCROLL_EPSILON,
+					isScrolling: scrollWidth > clientWidth,
+				} );
+			};
+
+			const resizeObserver = new ResizeObserver( measureOverflow );
+			resizeObserver.observe( listEl );
+
+			let scrollTick = false;
+			const throttleMeasureOverflowOnScroll = () => {
+				if ( ! scrollTick ) {
+					requestAnimationFrame( () => {
+						measureOverflow();
+						scrollTick = false;
+					} );
+					scrollTick = true;
+				}
+			};
+			listEl.addEventListener(
+				'scroll',
+				throttleMeasureOverflowOnScroll,
+				{ passive: true }
+			);
+
+			// Initial check.
+			measureOverflow();
+
+			return () => {
+				listEl.removeEventListener(
+					'scroll',
+					throttleMeasureOverflowOnScroll
+				);
+				resizeObserver.disconnect();
+			};
+		}, [ listEl ] );
+
+		const mergedListRef = useMergeRefs( [
+			forwardedRef,
+			( el: HTMLDivElement | null ) => setListEl( el ),
+		] );
+
+		return (
+			<_Tabs.List
+				ref={ mergedListRef }
+				activateOnFocus={ activateOnFocus }
+				data-select-on-move={ activateOnFocus ? 'true' : 'false' }
+				className={ clsx(
+					styles.tablist,
+					overflow.first && styles[ 'is-overflowing-first' ],
+					overflow.last && styles[ 'is-overflowing-last' ],
+					styles[ `is-${ variant }-variant` ],
+					className
+				) }
+				{ ...otherProps }
+				tabIndex={
+					otherProps.tabIndex ??
+					( overflow.isScrolling ? -1 : undefined )
+				}
+			>
+				{ children }
+				<_Tabs.Indicator className={ styles.indicator } />
+			</_Tabs.List>
+		);
+	}
+);

packages/ui/src/tabs/panel.tsx

@@ -0,0 +1,23 @@
+import { forwardRef } from '@wordpress/element';
+import clsx from 'clsx';
+import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import styles from './style.module.css';
+import type { TabPanelProps } from './types';
+
+/**
+ * A panel displayed when the corresponding tab is active.
+ *
+ * `Tabs` is a collection of React components that combine to render
+ * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ */
+export const Panel = forwardRef< HTMLDivElement, TabPanelProps >(
+	function TabPanel( { className, ...otherProps }, forwardedRef ) {
+		return (
+			<_Tabs.Panel
+				ref={ forwardedRef }
+				className={ clsx( styles.tabpanel, className ) }
+				{ ...otherProps }
+			/>
+		);
+	}
+);

packages/ui/src/tabs/root.tsx

@@ -0,0 +1,15 @@
+import { forwardRef } from '@wordpress/element';
+import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import type { TabRootProps } from './types';
+
+/**
+ * Groups the tabs and the corresponding panels.
+ *
+ * `Tabs` is a collection of React components that combine to render
+ * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ */
+export const Root = forwardRef< HTMLDivElement, TabRootProps >(
+	function TabsRoot( { ...otherProps }, forwardedRef ) {
+		return <_Tabs.Root ref={ forwardedRef } { ...otherProps } />;
+	}
+);

packages/ui/src/tabs/stories/best-practices.mdx

@@ -0,0 +1,85 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Design System/Components/Tabs/Best Practices" />
+
+# Tabs
+
+## Usage
+
+### Uncontrolled Mode
+
+`Tabs` can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultValue` prop can be used to set the initially selected tab.
+
+```jsx
+import { Tabs } from '@wordpress/ui';
+
+const MyUncontrolledTabs = () => (
+	<Tabs.Root
+		onValueChange={ ( tab ) => console.log( 'New selected tab: ', tab ) }
+		defaultValue="tab2"
+	>
+		<Tabs.List>
+			<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+			<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+			<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+		</Tabs.List>
+		<Tabs.Panel value="tab1">
+			<p>Selected tab: Tab 1</p>
+		</Tabs.Panel>
+		<Tabs.Panel value="tab2">
+			<p>Selected tab: Tab 2</p>
+		</Tabs.Panel>
+		<Tabs.Panel value="tab3">
+			<p>Selected tab: Tab 3</p>
+		</Tabs.Panel>
+	</Tabs.Root>
+);
+```
+
+### Controlled Mode
+
+Tabs can also be used in a controlled mode, where the parent component uses the `value` and `onValueChange` props to control tab selection. In this mode, the `defaultValue` prop will be ignored if it is provided. To indicate that no tabs are selected, pass `null` to the `value`.
+
+```tsx
+import { useState } from 'react';
+import { Tabs } from '@wordpress/ui';
+
+const MyControlledTabs = () => {
+	const [ selectedTabId, setSelectedTabId ] = useState<
+		string | undefined | null
+	>( null );
+
+	return (
+		<Tabs.Root
+			value={ selectedTabId }
+			onValueChange={ ( newSelectedTabId ) => {
+				setSelectedTabId( newSelectedTabId );
+				console.log( 'Selecting tab', newSelectedTabId );
+			} }
+		>
+			<Tabs.List>
+				<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+				<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+				<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+			</Tabs.List>
+			<Tabs.Panel value="tab1">
+				<p>Selected tab: Tab 1</p>
+			</Tabs.Panel>
+			<Tabs.Panel value="tab2">
+				<p>Selected tab: Tab 2</p>
+			</Tabs.Panel>
+			<Tabs.Panel value="tab3">
+				<p>Selected tab: Tab 3</p>
+			</Tabs.Panel>
+		</Tabs.Root>
+	);
+};
+```
+
+### Using `Tabs` with links
+
+The semantics implemented by the `Tabs` component don't align well with the semantics needed by a list of links. Furthermore, end users usually expect every link to be tabbable, while `Tabs.List` is a [composite](https://w3c.github.io/aria/#composite) widget acting as a single tab stop.
+
+For these reasons, even if the `Tabs` component is fully extensible, we don't recommend using `Tabs` with links, and we don't currently provide any related Storybook example.
+
+We may provide a dedicated component for tabs-like links in the future based on the feedback received.