An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Tab.tsx
* @input Uses React, StyleX, TabListContext
* @output Exports Tab component and TabProps type
* @position Core tab item; renders as button or anchor in navigation with a
* divider-overlay selected indicator. Where the TabList speaks the tabs
* pattern it is a button with role="tab".
*
* SYNC: When modified, update:
* - /packages/core/src/TabList/TabList.doc.mjs
* - /packages/core/src/TabList/index.ts
* - /packages/core/src/TabList/TabList.test.tsx
* - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
*/
import React, {useCallback, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
sizeVars,
radiusVars,
durationVars,
easeVars,
fontWeightVars,
typeScaleVars,
} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {useTabListContext} from './TabListContext';
import type {TabListSize} from './TabListContext';
import {tabScope} from './tab.markers.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {useLinkComponent} from '../Link/useLinkComponent';
import type {LinkComponentType} from '../Link/types';
import {mergeProps} from '../utils';
import {useDevWarning} from '../hooks/useDevWarning';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {isRenderable} from '../utils/isRenderable';
export interface TabProps extends BaseProps<HTMLButtonElement> {
/**
* Custom component to render instead of `<a>` for link tabs.
* Overrides the provider-level default set by LinkProvider.
* Only applies when `href` is provided. Must accept href, className, style, and children props.
*/
as?: LinkComponentType;
ref?: React.Ref<HTMLButtonElement>;
/**
* Unique value for this tab. Matched against TabListContext.value.
*/
value: string;
/**
* Accessible label for this tab. Used as visible text by default, or
* as aria-label when isLabelHidden is true.
*/
label: string;
/**
* Whether the label is visually hidden. When true, only the icon and
* endContent are displayed, and label is used as aria-label for accessibility.
* @default false
*/
isLabelHidden?: boolean;
/**
* URL to navigate to. When provided, renders as an anchor element.
*
* Ignored in a TabList given an explicit `role="tablist"`: activating a tab
* there swaps a panel in place, so a tab that navigates would be a false
* statement.
*/
href?: string;
/**
* Id of the panel this tab controls, wired up as `aria-controls` where the
* TabList speaks the tabs pattern. Put the same id on the panel element.
*
* Has no effect under the navigation pattern, where there is no panel to
* associate — a development warning says so.
*/
panelId?: string;
/**
* Icon element shown when tab is not selected.
*/
icon?: ReactNode;
/**
* Icon element shown when tab is selected. Falls back to `icon` if not provided.
*/
selectedIcon?: ReactNode;
/**
* Content rendered after the label (e.g. a badge or status dot).
*/
endContent?: ReactNode;
}
// =============================================================================
// Styles
// =============================================================================
// The touch press's paint, declared by the shared overlay styles on the
// element the controller writes to (`pressedAlpha`) at the press's strength,
// 1 while on and 1 → 0 over the release, and inherited resolved by the layer
// that paints it. See interactionOverlay.stylex.ts.
const pressedOverlayImage = 'var(--_press-paint-image)';
const styles = stylex.create({
base: {
position: 'relative',
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
gap: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-3'],
backgroundColor: 'transparent',
borderWidth: 0,
borderStyle: 'none',
borderRadius: radiusVars['--radius-element'],
fontFamily: 'inherit',
fontSize: typeScaleVars['--text-label-size'],
lineHeight: typeScaleVars['--text-label-leading'],
fontWeight: fontWeightVars['--font-weight-normal'],
color: colorVars['--color-text-secondary'],
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
textDecoration: 'none',
whiteSpace: 'nowrap',
transitionProperty: 'color',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
},
hoverBg: {
position: 'absolute',
inset: 0,
margin: 'auto',
width: '100%',
borderRadius: radiusVars['--radius-element'],
pointerEvents: 'none',
backgroundColor: {
default: 'transparent',
[stylex.when.ancestor(':hover', tabScope)]: {
'@media (hover: hover)': colorVars['--color-overlay-hover'],
},
// Pressed: the same layer steps up to the pressed overlay, read off the
// tab the way the hover is, so a press paints on a finger too. Repeated
// inside the hover-capable branch so it outranks the hover rule there
// (a media-nested rule carries extra generated priority; see
// interactionOverlay.stylex.ts).
[stylex.when.ancestor(':active', tabScope)]: {
default: colorVars['--color-overlay-pressed'],
'@media (hover: hover)': colorVars['--color-overlay-pressed'],
// Under a coarse pointer the touch press model writes `data-astryx-press`
// on the tab instead, and paints as an image below.
'@media (pointer: coarse)': 'transparent',
},
},
// The touch press, as an image layer over the colour: an image change is
// discrete, so the layer's colour transition cannot fade the onset in,
// and the strength the tab's `pressedAlpha` arms own (1 while on, 1 → 0
// over the release) is what moves. Coarse pointers only, like the colour
// arms above; see interactionOverlay.stylex.ts.
backgroundImage: {
default: null,
[stylex.when.ancestor('[data-astryx-press="on"]', tabScope)]: {
default: null,
'@media (pointer: coarse)': pressedOverlayImage,
},
[stylex.when.ancestor('[data-astryx-press="fading"]', tabScope)]: {
default: null,
'@media (pointer: coarse)': pressedOverlayImage,
},
},
transitionProperty: 'background-color',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
},
selected: {
color: colorVars['--color-text-primary'],
fontWeight: fontWeightVars['--font-weight-semibold'],
},
indicator: {
position: 'absolute',
// Sits on the tab's bottom edge by default (-1px). When the tab strip
// reserves space for a divider rail — TabList `hasDivider` or a Toolbar
// with a bottom divider — that ancestor sets `--_tab-indicator-bottom`
// to drop the indicator onto the rail beneath the reserved gap.
bottom: 'var(--_tab-indicator-bottom, -1px)',
insetInlineStart: spacingVars['--spacing-3'],
insetInlineEnd: spacingVars['--spacing-3'],
height: '2px',
borderRadius: radiusVars['--radius-full'],
pointerEvents: 'none',
transitionProperty: 'opacity, background-color',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
},
indicatorSelected: {
backgroundColor: colorVars['--color-accent'],
opacity: 1,
},
indicatorUnselected: {
backgroundColor: 'transparent',
opacity: 0,
},
icon: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
},
labelContainer: {
display: 'inline-grid',
},
labelText: {
gridRowStart: 1,
gridColumnStart: 1,
},
labelSizer: {
gridRowStart: 1,
gridColumnStart: 1,
visibility: 'hidden',
pointerEvents: 'none',
fontWeight: fontWeightVars['--font-weight-semibold'],
},
endContentWrapper: {
display: 'inline-flex',
alignItems: 'center',
flexShrink: 0,
},
});
// A minimum, not a fixed height: a tab grows with a larger text size, so its
// label is never clipped.
const sizeStyles = stylex.create({
sm: {minHeight: sizeVars['--size-element-sm']},
md: {minHeight: sizeVars['--size-element-md']},
lg: {minHeight: sizeVars['--size-element-lg']},
});
// The hover background fills the tab (inset 0) and is never shorter than the
// element size.
const hoverSizeStyles = stylex.create({
sm: {minHeight: sizeVars['--size-element-sm']},
md: {minHeight: sizeVars['--size-element-md']},
lg: {minHeight: sizeVars['--size-element-lg']},
});
const layoutStyles = stylex.create({
// A hugging tab keeps its label's width. Without this the strip's flex
// shrinks every tab below its text before overflow can scroll, and on a
// narrow screen the labels draw over one another.
hug: {
flexShrink: 0,
},
fill: {
flex: 1,
justifyContent: 'center',
},
});
const iconSizeStyles = stylex.create({
sm: {width: '14px', height: '14px'},
md: {width: '16px', height: '16px'},
lg: {width: '18px', height: '18px'},
});
/**
* Tab item component. Renders as an anchor when `href` is provided,
* otherwise as a button.
*
* @example
* ```
* <TabList value={tab} onChange={setTab}>
* <Tab value="general" label="General" />
* <Tab value="advanced" label="Advanced" />
* </TabList>
* ```
*/
export function Tab({
as,
ref,
value,
label,
isLabelHidden = false,
href,
panelId,
icon,
selectedIcon,
endContent,
xstyle,
className,
style,
onClick,
...restProps
}: TabProps) {
const pressable = usePressFeedback();
const tabListCtx = useTabListContext();
const LinkComponent = useLinkComponent(as);
const isSelected = tabListCtx.value === value;
const size: TabListSize = tabListCtx.size;
const isFill = tabListCtx.layout === 'fill';
const isTabsPattern = tabListCtx.pattern === 'tabs';
const isLink = href != null && !isTabsPattern;
const isTabRole = isTabsPattern && !isLink;
const displayIcon =
isSelected && isRenderable(selectedIcon) ? selectedIcon : icon;
const hasVisibleLabel = !isLabelHidden && label !== '';
const isDisabled =
restProps['aria-disabled'] === true ||
restProps['aria-disabled'] === 'true';
const handleSelect = useCallback(
(event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => {
if (isDisabled) {
event.preventDefault();
return;
}
onClick?.(event as React.MouseEvent<HTMLButtonElement>);
if (!event.defaultPrevented) {
tabListCtx.onChange(value);
}
},
[isDisabled, onClick, tabListCtx, value],
);
useDevWarning(
'Tab',
'href is ignored in a role="tablist" TabList — a tab swaps a panel in ' +
'place rather than navigating. Drop the href, or drop the role for the ' +
'navigation pattern.',
isTabRole && href != null,
);
// A consumer who wired aria-controls by hand already said which panel this
// is, so panelId is the sugar, not the only way in.
const controls = panelId ?? restProps['aria-controls'];
useDevWarning(
'Tab',
'a tab in a role="tablist" TabList controls nothing: pass panelId with ' +
'the id of the panel it opens, so assistive technology can associate ' +
'the two.',
isTabRole && controls == null,
);
useDevWarning(
'Tab',
'panelId does nothing outside a role="tablist" TabList — the navigation ' +
'pattern has no panel to associate. Give the TabList role="tablist", ' +
'or drop the panelId.',
!isTabsPattern && panelId != null,
);
const iconElement = isRenderable(displayIcon) ? (
<span {...stylex.props(styles.icon, iconSizeStyles[size])}>
{displayIcon}
</span>
) : null;
const sharedProps = {
// A disabled tab keeps its tab stop, so the browser still sends it events.
// It runs no caller handler other than `onFocus` and `onBlur`, as a natively
// disabled control runs none. `onClick` is guarded in `handleSelect`.
...withholdCallerHandlers(restProps, isDisabled),
...pressable,
...(isLabelHidden ? {'aria-label': label} : {}),
[EDGE_COMP_ATTR]: '',
'data-tab-value': value,
...(isTabRole
? {
role: 'tab' as const,
'aria-selected': isSelected,
// Only when there is a panel to point at: an aria-controls whose
// target does not exist is an invalid attribute value, which is a
// worse state than saying nothing. The dev warning above asks for
// the id instead.
'aria-controls': controls,
}
: {
// Generic `true` ("the current item within a set"), not `page`: the
// strip switches views in place at least as often as it navigates,
// and claiming "current page" when no page changed is a false
// statement to a screen reader. Stays truthful for the `href` case
// too, just less specific. A tab role states this with
// aria-selected instead.
'aria-current': isSelected ? ('true' as const) : undefined,
}),
// Roving tabindex: the tab strip is a single Tab stop. The selected tab is
// the tabbable one; the rest are reachable via arrow keys (handled by
// TabList's onKeyDown). When no tab is selected, TabList's repair effect
// makes the first stop tabbable.
tabIndex: isSelected ? 0 : -1,
...mergeProps(
themeProps('tab', {
selected: isSelected ? 'selected' : null,
}),
focusOutlineProps.focusVisible(
styles.base,
sizeStyles[size],
isSelected && styles.selected,
isFill ? layoutStyles.fill : layoutStyles.hug,
!isDisabled && tabScope,
// The touch press's strength and release live on the tab the
// controller writes to; the hover layer inherits and paints it.
!isDisabled && interactionOverlayStyles.pressedAlpha,
xstyle,
),
className,
style,
),
};
const hoverBgElement = (
<span
aria-hidden="true"
{...stylex.props(styles.hoverBg, hoverSizeStyles[size])}
/>
);
const indicatorElement = (
<span
{...mergeProps(
themeProps('tab-indicator', {
selected: isSelected ? 'selected' : null,
}),
stylex.props(
styles.indicator,
isSelected ? styles.indicatorSelected : styles.indicatorUnselected,
),
)}
/>
);
const labelElement = hasVisibleLabel ? (
<span {...stylex.props(styles.labelContainer)}>
<span {...stylex.props(styles.labelText)}>{label}</span>
<span aria-hidden="true" {...stylex.props(styles.labelSizer)}>
{label}
</span>
</span>
) : null;
const endContentElement = isRenderable(endContent) ? (
<span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
) : null;
if (isLink) {
// A disabled link tab must not reach a router component: some routers reject
// a missing destination, while others treat it as the current route. A
// plain anchor without href preserves the element shape but cannot navigate.
const LinkRoot = isDisabled ? 'a' : LinkComponent;
return (
<LinkRoot
ref={ref}
href={isDisabled ? undefined : href}
onClick={handleSelect}
{...sharedProps}>
{hoverBgElement}
{iconElement}
{labelElement}
{endContentElement}
{indicatorElement}
</LinkRoot>
);
}
return (
<button ref={ref} type="button" onClick={handleSelect} {...sharedProps}>
{hoverBgElement}
{iconElement}
{labelElement}
{endContentElement}
{indicatorElement}
</button>
);
}
Tab.displayName = 'Tab';