Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(tablist): align icon-only tab indicator (#2786)

Cindy Zhang54491c4daf09
diff --git a/.changeset/icon-only-tab-indicator.md b/.changeset/icon-only-tab-indicator.md
new file mode 100644
index 0000000000..9a26e4bd7c
--- /dev/null
+++ b/.changeset/icon-only-tab-indicator.md
@@ -0,0 +1,5 @@
+---
+'@xds/core': patch
+---
+
+`XDSTab`: add `isLabelHidden` for icon-only tabs and omit empty label nodes so selected indicators align with the visible icon.
diff --git a/apps/storybook/stories/TabList.stories.tsx b/apps/storybook/stories/TabList.stories.tsx
index 08fcf7a727..fce3273dcd 100644
--- a/apps/storybook/stories/TabList.stories.tsx
+++ b/apps/storybook/stories/TabList.stories.tsx
@@ -146,6 +146,51 @@ export const WithIcons: Story = {
},
};
+export const IconOnly: Story = {
+ args: {
+ size: 'md',
+ },
+ render: args => {
+ const [value, setValue] = useState('desktop');
+
+ const DesktopIcon = (
+ <svg viewBox="0 0 16 16" fill="currentColor" width="100%" height="100%">
+ <path d="M2.5 3A1.5 1.5 0 0 0 1 4.5v5A1.5 1.5 0 0 0 2.5 11h4.75v1.5H5a.75.75 0 0 0 0 1.5h6a.75.75 0 0 0 0-1.5H8.75V11h4.75A1.5 1.5 0 0 0 15 9.5v-5A1.5 1.5 0 0 0 13.5 3h-11Zm0 1.5h11v5h-11v-5Z" />
+ </svg>
+ );
+
+ const PhoneIcon = (
+ <svg viewBox="0 0 16 16" fill="currentColor" width="100%" height="100%">
+ <path d="M5 1.5A1.5 1.5 0 0 0 3.5 3v10A1.5 1.5 0 0 0 5 14.5h6a1.5 1.5 0 0 0 1.5-1.5V3A1.5 1.5 0 0 0 11 1.5H5Zm0 1.5h6v10H5V3Zm2.25 8.5a.75.75 0 0 1 .75-.75h.01a.75.75 0 0 1 0 1.5H8a.75.75 0 0 1-.75-.75Z" />
+ </svg>
+ );
+
+ const ThemeIcon = (
+ <svg viewBox="0 0 16 16" fill="currentColor" width="100%" height="100%">
+ <path d="M8 1.5a6.5 6.5 0 0 0 0 13h.25a1.75 1.75 0 0 0 1.2-3.02.35.35 0 0 1 .23-.6h.97A3.85 3.85 0 0 0 14.5 7.03 5.53 5.53 0 0 0 8.97 1.5H8Zm-3 5a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm2-1.75a1 1 0 1 1 2 0 1 1 0 0 1-2 0ZM4.5 9a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm6-1.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z" />
+ </svg>
+ );
+
+ return (
+ <XDSTabList value={value} onChange={setValue} size={args.size}>
+ <XDSTab
+ value="desktop"
+ label="Desktop preview"
+ icon={DesktopIcon}
+ isLabelHidden
+ />
+ <XDSTab
+ value="phone"
+ label="Phone preview"
+ icon={PhoneIcon}
+ isLabelHidden
+ />
+ <XDSTab value="theme" label="Theme" icon={ThemeIcon} isLabelHidden />
+ </XDSTabList>
+ );
+ },
+};
+
/**
* Demonstrates a common page header pattern: large tab list items on the left
* with action buttons on the right, separated by a full-width divider underneath.
diff --git a/packages/core/src/TabList/Tab.doc.mjs b/packages/core/src/TabList/Tab.doc.mjs
index 1aa7e166ba..002ea8c945 100644
--- a/packages/core/src/TabList/Tab.doc.mjs
+++ b/packages/core/src/TabList/Tab.doc.mjs
@@ -7,29 +7,41 @@ export const docs = {
subComponentOf: 'TabList',
displayName: 'Tab',
isHiddenFromOverview: true,
- description: 'Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.',
+ description:
+ 'Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.',
props: [
{
name: 'value',
type: 'string',
- description: 'Unique value for this tab, matched against XDSTabListContext.value.',
+ description:
+ 'Unique value for this tab, matched against XDSTabListContext.value.',
required: true,
},
{
name: 'label',
type: 'string',
- description: 'Visible label text for this tab.',
+ description:
+ 'Accessible label for this tab. Used as visible text by default, or as aria-label when isLabelHidden is true.',
required: true,
},
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ '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',
+ },
{
name: 'href',
type: 'string',
- description: 'URL to navigate to; when provided, the tab renders as an anchor element.',
+ description:
+ 'URL to navigate to; when provided, the tab renders as an anchor element.',
},
{
name: 'as',
type: 'XDSLinkComponentType',
- description: 'Custom component to render instead of <a> for link tabs. Overrides the XDSLinkProvider default. Only applies when href is provided.',
+ description:
+ 'Custom component to render instead of <a> for link tabs. Overrides the XDSLinkProvider default. Only applies when href is provided.',
},
{
name: 'icon',
@@ -48,7 +60,8 @@ export const docs = {
{
name: 'selectedIcon',
type: 'ReactNode',
- description: 'Icon element shown when the tab is selected; falls back to icon if not provided.',
+ description:
+ 'Icon element shown when the tab is selected; falls back to icon if not provided.',
slotElements: [
{
__element: 'XDSIcon',
@@ -62,7 +75,8 @@ export const docs = {
{
name: 'endContent',
type: 'ReactNode',
- description: 'Content rendered after the label, such as a badge count or status dot.',
+ description:
+ 'Content rendered after the label, such as a badge count or status dot.',
slotElements: [
{
__element: 'XDSIcon',
@@ -82,7 +96,8 @@ export const docs = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ description:
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
},
],
};
@@ -102,9 +117,17 @@ export const docsZh = {
{
name: 'label',
type: 'string',
- description: '此标签的可见标签文本。',
+ description:
+ '此标签的无障碍标签。默认作为可见文本使用;当 isLabelHidden 为 true 时用作 aria-label。',
required: true,
},
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ '是否在视觉上隐藏标签。为 true 时,仅显示图标和 endContent,并将 label 用作无障碍 aria-label。',
+ default: 'false',
+ },
{
name: 'href',
type: 'string',
@@ -113,7 +136,8 @@ export const docsZh = {
{
name: 'as',
type: 'XDSLinkComponentType',
- description: '用于替代 <a> 渲染链接标签的自定义组件。覆盖 XDSLinkProvider 的默认值。仅在提供 href 时生效。',
+ description:
+ '用于替代 <a> 渲染链接标签的自定义组件。覆盖 XDSLinkProvider 的默认值。仅在提供 href 时生效。',
},
{
name: 'icon',
@@ -133,7 +157,8 @@ export const docsZh = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
+ description:
+ 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
},
],
};
@@ -142,15 +167,20 @@ export const docsDense = {
name: 'Tab',
isHiddenFromOverview: true,
displayName: 'Tab',
- description: 'Individual tab; renders as button or anchor w/ selected-state styling + optional icons.',
+ description:
+ 'Individual tab; renders as button or anchor w/ selected-state styling + optional icons.',
propDescriptions: {
value: 'Unique value matched against XDSTabListContext.value.',
- label: 'Visible label text.',
+ label:
+ 'Accessible label; visible by default, aria-label when isLabelHidden.',
+ isLabelHidden:
+ 'Visually hide label for icon-only tabs; label becomes aria-label.',
href: 'URL; renders as <a> when provided.',
as: 'Custom link component overriding XDSLinkProvider; only w/ href.',
icon: 'Icon shown when not selected.',
selectedIcon: 'Icon shown when selected; falls back to icon.',
endContent: 'Content after the label (badge, status dot, etc.).',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
+ xstyle:
+ 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
},
};
diff --git a/packages/core/src/TabList/XDSTab.tsx b/packages/core/src/TabList/XDSTab.tsx
index e3fc80ff0e..2415a5b007 100644
--- a/packages/core/src/TabList/XDSTab.tsx
+++ b/packages/core/src/TabList/XDSTab.tsx
@@ -50,9 +50,16 @@ export interface XDSTabProps extends XDSBaseProps<HTMLButtonElement> {
*/
value: string;
/**
- * Visible label text for this tab.
+ * 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.
*/
@@ -218,6 +225,7 @@ export function XDSTab({
ref,
value,
label,
+ isLabelHidden = false,
href,
icon,
selectedIcon,
@@ -234,6 +242,7 @@ export function XDSTab({
const size: XDSTabListSize = tabListCtx.size;
const isFill = tabListCtx.layout === 'fill';
const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
+ const hasVisibleLabel = !isLabelHidden && label !== '';
const handleSelect = useCallback(() => {
tabListCtx.onChange(value);
@@ -247,6 +256,7 @@ export function XDSTab({
const sharedProps = {
...restProps,
+ ...(isLabelHidden ? {'aria-label': label} : {}),
[EDGE_COMP_ATTR]: '',
'aria-current': isSelected ? ('page' as const) : undefined,
...mergeProps(
@@ -287,14 +297,14 @@ export function XDSTab({
/>
);
- const labelElement = (
+ 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 = endContent ? (
<span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
diff --git a/packages/core/src/TabList/XDSTabList.test.tsx b/packages/core/src/TabList/XDSTabList.test.tsx
index e0bdb6edc6..ee1c2ea379 100644
--- a/packages/core/src/TabList/XDSTabList.test.tsx
+++ b/packages/core/src/TabList/XDSTabList.test.tsx
@@ -166,6 +166,42 @@ describe('XDSTabList', () => {
expect(screen.getByTestId('icon')).toBeInTheDocument();
});
+ it('renders icon-only tab with aria-label from label prop', () => {
+ render(
+ <XDSTabList value="preview" onChange={() => {}}>
+ <XDSTab
+ value="preview"
+ label="Preview"
+ isLabelHidden
+ icon={<span data-testid="icon">▣</span>}
+ />
+ </XDSTabList>,
+ );
+
+ const tab = screen.getByRole('button', {name: 'Preview'});
+ expect(tab).toHaveAttribute('aria-label', 'Preview');
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ expect(screen.queryByText('Preview')).not.toBeInTheDocument();
+ });
+
+ it('omits empty label nodes so aria-labeled icon tabs align to the icon', () => {
+ render(
+ <XDSTabList value="preview" onChange={() => {}}>
+ <XDSTab
+ value="preview"
+ label=""
+ aria-label="Preview"
+ icon={<span data-testid="icon">▣</span>}
+ />
+ </XDSTabList>,
+ );
+
+ const tab = screen.getByRole('button', {name: 'Preview'});
+ expect(tab).toBeInTheDocument();
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ expect(tab.querySelectorAll(':scope > span').length).toBe(3);
+ });
+
it('renders selectedIcon when tab is selected', () => {
render(
<XDSTabList value="home" onChange={() => {}}>