Skip to content

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

TypeScript

segmented control (#725)

Andrey Godera4adf06f4564
diff --git a/apps/storybook/stories/SegmentedControl.stories.tsx b/apps/storybook/stories/SegmentedControl.stories.tsx
new file mode 100644
index 0000000000..986dcd03ce
--- /dev/null
+++ b/apps/storybook/stories/SegmentedControl.stories.tsx
@@ -0,0 +1,200 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSSegmentedControl,
+ XDSSegmentedControlItem,
+} from '@xds/core/SegmentedControl';
+import {XDSIcon} from '@xds/core/Icon';
+import {
+ Squares2X2Icon,
+ ListBulletIcon,
+ TableCellsIcon,
+} from '@heroicons/react/24/outline';
+
+const meta: Meta<typeof XDSSegmentedControl> = {
+ title: 'Inputs/XDSSegmentedControl',
+ component: XDSSegmentedControl,
+ tags: ['autodocs'],
+ argTypes: {
+ size: {
+ control: 'select',
+ options: ['sm', 'md', 'lg'],
+ description: 'Size variant for the control',
+ },
+ isDisabled: {
+ control: 'boolean',
+ description: 'Whether the entire control is disabled',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSSegmentedControl>;
+
+export const Default: Story = {
+ args: {
+ size: 'md',
+ isDisabled: false,
+ },
+ render: args => {
+ const [value, setValue] = useState('grid');
+ return (
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="View mode"
+ size={args.size}
+ isDisabled={args.isDisabled}>
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>
+ );
+ },
+};
+
+export const WithIcons: Story = {
+ args: {
+ size: 'md',
+ },
+ render: args => {
+ const [value, setValue] = useState('grid');
+ return (
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="View mode"
+ size={args.size}>
+ <XDSSegmentedControlItem
+ value="grid"
+ label="Grid"
+ icon={<XDSIcon icon={Squares2X2Icon} color="inherit" />}
+ />
+ <XDSSegmentedControlItem
+ value="list"
+ label="List"
+ icon={<XDSIcon icon={ListBulletIcon} color="inherit" />}
+ />
+ <XDSSegmentedControlItem
+ value="table"
+ label="Table"
+ icon={<XDSIcon icon={TableCellsIcon} color="inherit" />}
+ />
+ </XDSSegmentedControl>
+ );
+ },
+};
+
+export const IconOnly: Story = {
+ args: {
+ size: 'sm',
+ },
+ render: args => {
+ const [value, setValue] = useState('grid');
+ return (
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="View mode"
+ size={args.size}>
+ <XDSSegmentedControlItem
+ value="grid"
+ label="Grid"
+ isLabelHidden
+ icon={<XDSIcon icon={Squares2X2Icon} color="inherit" />}
+ />
+ <XDSSegmentedControlItem
+ value="list"
+ label="List"
+ isLabelHidden
+ icon={<XDSIcon icon={ListBulletIcon} color="inherit" />}
+ />
+ </XDSSegmentedControl>
+ );
+ },
+};
+
+export const SizeVariants: Story = {
+ render: () => {
+ const [value, setValue] = useState('day');
+ return (
+ <div style={{display: 'flex', flexDirection: 'column', gap: '24px'}}>
+ <div>
+ <div style={{marginBottom: '8px', fontSize: '12px', color: '#666'}}>
+ Small
+ </div>
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="Time period"
+ size="sm">
+ <XDSSegmentedControlItem value="day" label="Day" />
+ <XDSSegmentedControlItem value="week" label="Week" />
+ <XDSSegmentedControlItem value="month" label="Month" />
+ </XDSSegmentedControl>
+ </div>
+ <div>
+ <div style={{marginBottom: '8px', fontSize: '12px', color: '#666'}}>
+ Medium (default)
+ </div>
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="Time period"
+ size="md">
+ <XDSSegmentedControlItem value="day" label="Day" />
+ <XDSSegmentedControlItem value="week" label="Week" />
+ <XDSSegmentedControlItem value="month" label="Month" />
+ </XDSSegmentedControl>
+ </div>
+ <div>
+ <div style={{marginBottom: '8px', fontSize: '12px', color: '#666'}}>
+ Large
+ </div>
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="Time period"
+ size="lg">
+ <XDSSegmentedControlItem value="day" label="Day" />
+ <XDSSegmentedControlItem value="week" label="Week" />
+ <XDSSegmentedControlItem value="month" label="Month" />
+ </XDSSegmentedControl>
+ </div>
+ </div>
+ );
+ },
+};
+
+export const Disabled: Story = {
+ render: () => {
+ const [value, setValue] = useState('all');
+ return (
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="Filter"
+ isDisabled>
+ <XDSSegmentedControlItem value="all" label="All" />
+ <XDSSegmentedControlItem value="active" label="Active" />
+ <XDSSegmentedControlItem value="completed" label="Completed" />
+ </XDSSegmentedControl>
+ );
+ },
+};
+
+export const DisabledItem: Story = {
+ render: () => {
+ const [value, setValue] = useState('hourly');
+ return (
+ <XDSSegmentedControl
+ value={value}
+ onChange={setValue}
+ label="Data granularity">
+ <XDSSegmentedControlItem value="hourly" label="Hourly" />
+ <XDSSegmentedControlItem value="daily" label="Daily" />
+ <XDSSegmentedControlItem value="weekly" label="Weekly" isDisabled />
+ </XDSSegmentedControl>
+ );
+ },
+};
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
new file mode 100644
index 0000000000..3ee3e123e0
--- /dev/null
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -0,0 +1,185 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SegmentedControl',
+ description:
+ 'Segmented button group for single selection with radio group semantics. Visually resembles a tab bar but controls a value, not a view.',
+ features: [
+ 'Context-based communication: XDSSegmentedControlContext passes value/onChange/size/isDisabled from parent to children',
+ 'Radio group semantics: role="radiogroup" with role="radio" items and aria-checked',
+ 'Roving tabindex: only the selected item is tabbable (tabIndex=0), others are tabIndex=-1',
+ 'Keyboard navigation: ArrowLeft/ArrowRight navigate + select, Home/End jump to first/last, wraps around',
+ 'Animated indicator: selected item has a raised surface background with box-shadow',
+ 'Icon + label or icon-only items (isLabelHidden hides label visually, keeps it as aria-label)',
+ 'Size variants: sm (compact for toolbars), md (default), lg (larger touch targets)',
+ 'Disabled state: entire group or individual items via aria-disabled (maintains focusability)',
+ 'Hover state: unselected items show overlay on hover with @media (hover: hover) guard',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSSegmentedControl value={view} onChange={setView} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+</XDSSegmentedControl>`,
+ },
+ {
+ label: 'With icons',
+ code: `<XDSSegmentedControl value={view} onChange={setView} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" icon={<XDSIcon icon={Squares2X2Icon} color="inherit" />} />
+ <XDSSegmentedControlItem value="list" label="List" icon={<XDSIcon icon={ListBulletIcon} color="inherit" />} />
+ <XDSSegmentedControlItem value="table" label="Table" icon={<XDSIcon icon={TableCellsIcon} color="inherit" />} />
+</XDSSegmentedControl>`,
+ },
+ {
+ label: 'Icon-only compact',
+ code: `<XDSSegmentedControl value={view} onChange={setView} label="View mode" size="sm">
+ <XDSSegmentedControlItem value="grid" label="Grid" isLabelHidden icon={<XDSIcon icon={Squares2X2Icon} color="inherit" />} />
+ <XDSSegmentedControlItem value="list" label="List" isLabelHidden icon={<XDSIcon icon={ListBulletIcon} color="inherit" />} />
+</XDSSegmentedControl>`,
+ },
+ {
+ label: 'Disabled',
+ code: `<XDSSegmentedControl value={view} onChange={setView} label="View mode" isDisabled>
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+</XDSSegmentedControl>`,
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-segmented-control', visualProps: ['size']},
+ {className: 'xds-segmented-control-item'},
+ ],
+ },
+ accessibility: [
+ 'Container has role="radiogroup" with aria-label from the label prop (never rendered visually)',
+ 'Items have role="radio" with aria-checked indicating selection state',
+ 'Roving tabindex: selected item has tabIndex=0, others have tabIndex=-1',
+ 'Arrow keys navigate and select simultaneously (radio group pattern)',
+ 'Disabled items use aria-disabled (not native disabled) to maintain focusability',
+ 'Icon-only items use isLabelHidden — label becomes aria-label',
+ ],
+ keyboard:
+ 'ArrowRight/ArrowLeft navigate and select (wrapping). Home/End jump to first/last item. Only the selected item is in the tab order.',
+ notes: [
+ 'Controlled-only — no uncontrolled mode in v1',
+ 'Horizontal-only — no vertical orientation in v1',
+ 'Deselection not allowed (radio semantics — always one selected)',
+ 'Uses aria-disabled instead of native disabled to maintain keyboard focusability',
+ 'Keyboard navigation skips disabled items',
+ 'Track background uses --color-secondary, selected indicator uses --color-surface with --shadow-base',
+ 'label prop on XDSSegmentedControl is aria-only (like XDSTabList aria-label), never rendered visually',
+ ],
+ components: [
+ {
+ name: 'XDSSegmentedControl',
+ description:
+ 'Container wrapper providing context (value, onChange, size, isDisabled) to XDSSegmentedControlItem children.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'The currently selected value (controlled).',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when a segment is selected.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for the radio group (used as aria-label, never rendered visually).',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant for the control.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the entire control is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSSegmentedControlItem children.',
+ required: true,
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'Additional StyleX styles for the container.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSSegmentedControl value={view} onChange={setView} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+</XDSSegmentedControl>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSSegmentedControlItem',
+ description:
+ 'Individual segment item rendering as a radio button within the segmented control.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description:
+ 'Unique value for this segment, matched against the parent value.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for this segment. Rendered as visible text unless isLabelHidden is true.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Whether the label is visually hidden. When true, only the icon is displayed and label is used as aria-label.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon element displayed before the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this individual item is disabled.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'With icon and label',
+ code: '<XDSSegmentedControlItem value="grid" label="Grid" icon={<XDSIcon icon={Squares2X2Icon} color="inherit" />} />',
+ },
+ {
+ label: 'Icon-only',
+ code: '<XDSSegmentedControlItem value="grid" label="Grid" isLabelHidden icon={<XDSIcon icon={Squares2X2Icon} color="inherit" />} />',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/SegmentedControl/XDSSegmentedControl.test.tsx b/packages/core/src/SegmentedControl/XDSSegmentedControl.test.tsx
new file mode 100644
index 0000000000..a9ce917d0d
--- /dev/null
+++ b/packages/core/src/SegmentedControl/XDSSegmentedControl.test.tsx
@@ -0,0 +1,416 @@
+/**
+ * @file XDSSegmentedControl.test.tsx
+ * @input Uses vitest, @testing-library/react, SegmentedControl components
+ * @output Unit tests for XDSSegmentedControl and XDSSegmentedControlItem
+ * @position Testing; validates SegmentedControl component implementation
+ *
+ * SYNC: When SegmentedControl components change, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSSegmentedControl} from './XDSSegmentedControl';
+import {XDSSegmentedControlItem} from './XDSSegmentedControlItem';
+
+describe('XDSSegmentedControl', () => {
+ it('renders a radiogroup with radio buttons', () => {
+ render(
+ <XDSSegmentedControl value="grid" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+ expect(screen.getByRole('radiogroup')).toHaveAttribute(
+ 'aria-label',
+ 'View mode',
+ );
+ expect(screen.getByRole('radio', {name: 'Grid'})).toBeInTheDocument();
+ expect(screen.getByRole('radio', {name: 'List'})).toBeInTheDocument();
+ });
+
+ it('marks selected item with aria-checked', () => {
+ render(
+ <XDSSegmentedControl value="grid" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
+ 'aria-checked',
+ 'true',
+ );
+ expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
+ 'aria-checked',
+ 'false',
+ );
+ });
+
+ it('calls onChange when an item is clicked', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ await user.click(screen.getByRole('radio', {name: 'List'}));
+ expect(handleChange).toHaveBeenCalledWith('list');
+ });
+
+ it('does not call onChange when clicking the already-selected item', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ await user.click(screen.getByRole('radio', {name: 'Grid'}));
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('updates aria-checked when value changes', () => {
+ const {rerender} = render(
+ <XDSSegmentedControl value="grid" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
+ 'aria-checked',
+ 'true',
+ );
+
+ rerender(
+ <XDSSegmentedControl value="list" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
+ 'aria-checked',
+ 'false',
+ );
+ expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
+ 'aria-checked',
+ 'true',
+ );
+ });
+
+ it('renders with different sizes', () => {
+ const {rerender} = render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={() => {}}
+ label="View mode"
+ size="sm">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ </XDSSegmentedControl>,
+ );
+ expect(screen.getByRole('radio', {name: 'Grid'})).toBeInTheDocument();
+
+ rerender(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={() => {}}
+ label="View mode"
+ size="lg">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ </XDSSegmentedControl>,
+ );
+ expect(screen.getByRole('radio', {name: 'Grid'})).toBeInTheDocument();
+ });
+
+ it('renders item with icon', () => {
+ render(
+ <XDSSegmentedControl value="grid" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem
+ value="grid"
+ label="Grid"
+ icon={<span data-testid="icon">G</span>}
+ />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ });
+
+ it('renders icon-only item with aria-label from label prop', () => {
+ render(
+ <XDSSegmentedControl value="grid" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem
+ value="grid"
+ label="Grid view"
+ isLabelHidden
+ icon={<span data-testid="icon">G</span>}
+ />
+ </XDSSegmentedControl>,
+ );
+
+ const radio = screen.getByRole('radio', {name: 'Grid view'});
+ expect(radio).toBeInTheDocument();
+ expect(radio).toHaveAttribute('aria-label', 'Grid view');
+ // Label text should not be visible
+ expect(screen.queryByText('Grid view')).not.toBeInTheDocument();
+ });
+
+ it('uses roving tabindex — selected item has tabIndex 0, others -1', () => {
+ render(
+ <XDSSegmentedControl value="list" onChange={() => {}} label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
+ 'tabIndex',
+ '-1',
+ );
+ expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
+ 'tabIndex',
+ '0',
+ );
+ expect(screen.getByRole('radio', {name: 'Table'})).toHaveAttribute(
+ 'tabIndex',
+ '-1',
+ );
+ });
+});
+
+describe('XDSSegmentedControl keyboard navigation', () => {
+ it('navigates with ArrowRight and selects', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'Grid'}).focus();
+ await user.keyboard('{ArrowRight}');
+
+ expect(handleChange).toHaveBeenCalledWith('list');
+ expect(screen.getByRole('radio', {name: 'List'})).toHaveFocus();
+ });
+
+ it('navigates with ArrowLeft and selects', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="list"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'List'}).focus();
+ await user.keyboard('{ArrowLeft}');
+
+ expect(handleChange).toHaveBeenCalledWith('grid');
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveFocus();
+ });
+
+ it('wraps around from last to first with ArrowRight', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="table"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'Table'}).focus();
+ await user.keyboard('{ArrowRight}');
+
+ expect(handleChange).toHaveBeenCalledWith('grid');
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveFocus();
+ });
+
+ it('wraps around from first to last with ArrowLeft', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'Grid'}).focus();
+ await user.keyboard('{ArrowLeft}');
+
+ expect(handleChange).toHaveBeenCalledWith('table');
+ expect(screen.getByRole('radio', {name: 'Table'})).toHaveFocus();
+ });
+
+ it('Home key focuses first item', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="table"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'Table'}).focus();
+ await user.keyboard('{Home}');
+
+ expect(handleChange).toHaveBeenCalledWith('grid');
+ expect(screen.getByRole('radio', {name: 'Grid'})).toHaveFocus();
+ });
+
+ it('End key focuses last item', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'Grid'}).focus();
+ await user.keyboard('{End}');
+
+ expect(handleChange).toHaveBeenCalledWith('table');
+ expect(screen.getByRole('radio', {name: 'Table'})).toHaveFocus();
+ });
+});
+
+describe('XDSSegmentedControl disabled state', () => {
+ it('marks entire group as disabled', () => {
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={() => {}}
+ label="View mode"
+ isDisabled>
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radiogroup')).toHaveAttribute(
+ 'aria-disabled',
+ 'true',
+ );
+ });
+
+ it('does not call onChange when group is disabled', async () => {
+ const user = userEvent.setup({pointerEventsCheck: 0});
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode"
+ isDisabled>
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" />
+ </XDSSegmentedControl>,
+ );
+
+ await user.click(screen.getByRole('radio', {name: 'List'}));
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('disables individual items', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" isDisabled />
+ </XDSSegmentedControl>,
+ );
+
+ expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
+ 'aria-disabled',
+ 'true',
+ );
+
+ await user.click(screen.getByRole('radio', {name: 'List'}));
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('skips disabled items during keyboard navigation', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+
+ render(
+ <XDSSegmentedControl
+ value="grid"
+ onChange={handleChange}
+ label="View mode">
+ <XDSSegmentedControlItem value="grid" label="Grid" />
+ <XDSSegmentedControlItem value="list" label="List" isDisabled />
+ <XDSSegmentedControlItem value="table" label="Table" />
+ </XDSSegmentedControl>,
+ );
+
+ screen.getByRole('radio', {name: 'Grid'}).focus();
+ await user.keyboard('{ArrowRight}');
+
+ // Should skip disabled "List" and go to "Table"
+ expect(handleChange).toHaveBeenCalledWith('table');
+ expect(screen.getByRole('radio', {name: 'Table'})).toHaveFocus();
+ });
+});
diff --git a/packages/core/src/SegmentedControl/XDSSegmentedControl.tsx b/packages/core/src/SegmentedControl/XDSSegmentedControl.tsx
new file mode 100644
index 0000000000..f9835c1259
--- /dev/null
+++ b/packages/core/src/SegmentedControl/XDSSegmentedControl.tsx
@@ -0,0 +1,195 @@
+/**
+ * @file XDSSegmentedControl.tsx
+ * @input Uses React, StyleX, XDSSegmentedControlContext
+ * @output Exports XDSSegmentedControl component and XDSSegmentedControlProps type
+ * @position Container wrapper; provides context to XDSSegmentedControlItem children
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+ * - /packages/core/src/SegmentedControl/index.ts
+ * - /packages/core/src/SegmentedControl/XDSSegmentedControl.test.tsx
+ */
+
+'use client';
+
+import {useMemo, useRef, useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars, spacingVars, radiusVars} from '../theme/tokens.stylex';
+import {XDSSegmentedControlContext} from './XDSSegmentedControlContext';
+import type {XDSSegmentedControlSize} from './XDSSegmentedControlContext';
+import {xdsClassName, mergeProps} from '../utils';
+
+export interface XDSSegmentedControlProps {
+ /**
+ * The currently selected value (controlled).
+ */
+ value: string;
+ /**
+ * Callback fired when a segment is selected.
+ */
+ onChange: (value: string) => void;
+ /**
+ * Accessible label for the radio group (used as aria-label, never rendered visually).
+ */
+ label: string;
+ /**
+ * Size variant for the control.
+ * @default 'md'
+ */
+ size?: XDSSegmentedControlSize;
+ /**
+ * Whether the entire control is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+ /**
+ * XDSSegmentedControlItem children.
+ */
+ children: ReactNode;
+ /**
+ * Additional StyleX styles for the container.
+ */
+ xstyle?: StyleXStyles;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ container: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-0-5'],
+ '--segmented-padding': spacingVars['--spacing-0-5'],
+ padding: 'var(--segmented-padding)',
+ backgroundColor: colorVars['--color-secondary'],
+ },
+ disabled: {
+ opacity: 0.5,
+ pointerEvents: 'none',
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {
+ '--segmented-radius': radiusVars['--radius-1'],
+ borderRadius: 'var(--segmented-radius)',
+ },
+ md: {
+ '--segmented-radius': radiusVars['--radius-2'],
+ borderRadius: 'var(--segmented-radius)',
+ },
+ lg: {
+ '--segmented-radius': radiusVars['--radius-2'],
+ borderRadius: 'var(--segmented-radius)',
+ },
+});
+
+/**
+ * Segmented button group for single selection (radio group semantics).
+ * Visually resembles a tab bar but controls a value, not a view.
+ *
+ * @example
+ * ```
+ * <XDSSegmentedControl value={view} onChange={setView} label="View mode">
+ * <XDSSegmentedControlItem value="grid" label="Grid" />
+ * <XDSSegmentedControlItem value="list" label="List" />
+ * <XDSSegmentedControlItem value="table" label="Table" />
+ * </XDSSegmentedControl>
+ * ```
+ */
+export function XDSSegmentedControl({
+ value,
+ onChange,
+ label,
+ size = 'md',
+ isDisabled = false,
+ children,
+ xstyle,
+}: XDSSegmentedControlProps) {
+ const containerRef = useRef<HTMLDivElement>(null);
+
+ const handleKeyDown = useCallback(
+ (e: React.KeyboardEvent) => {
+ if (isDisabled) return;
+
+ const container = containerRef.current;
+ if (!container) return;
+
+ const items = Array.from(
+ container.querySelectorAll<HTMLButtonElement>(
+ '[role="radio"]:not([aria-disabled="true"])',
+ ),
+ );
+ if (items.length === 0) return;
+
+ const currentIndex = items.findIndex(
+ item => item === document.activeElement,
+ );
+ let nextIndex: number | null = null;
+
+ switch (e.key) {
+ case 'ArrowRight':
+ nextIndex =
+ currentIndex === -1 ? 0 : (currentIndex + 1) % items.length;
+ break;
+ case 'ArrowLeft':
+ nextIndex =
+ currentIndex === -1
+ ? items.length - 1
+ : (currentIndex - 1 + items.length) % items.length;
+ break;
+ case 'Home':
+ nextIndex = 0;
+ break;
+ case 'End':
+ nextIndex = items.length - 1;
+ break;
+ default:
+ return;
+ }
+
+ if (nextIndex != null) {
+ e.preventDefault();
+ const nextItem = items[nextIndex];
+ nextItem.focus();
+ const nextValue = nextItem.dataset.value;
+ if (nextValue != null) {
+ onChange(nextValue);
+ }
+ }
+ },
+ [isDisabled, onChange],
+ );
+
+ const contextValue = useMemo(
+ () => ({value, onChange, size, isDisabled}),
+ [value, onChange, size, isDisabled],
+ );
+
+ return (
+ <XDSSegmentedControlContext.Provider value={contextValue}>
+ <div
+ ref={containerRef}
+ role="radiogroup"
+ aria-label={label}
+ aria-disabled={isDisabled || undefined}
+ onKeyDown={handleKeyDown}
+ {...mergeProps(
+ xdsClassName('segmented-control', {size}),
+ stylex.props(
+ styles.container,
+ sizeStyles[size],
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ )}>
+ {children}
+ </div>
+ </XDSSegmentedControlContext.Provider>
+ );
+}
+
+XDSSegmentedControl.displayName = 'XDSSegmentedControl';
diff --git a/packages/core/src/SegmentedControl/XDSSegmentedControlContext.ts b/packages/core/src/SegmentedControl/XDSSegmentedControlContext.ts
new file mode 100644
index 0000000000..fe09f893f2
--- /dev/null
+++ b/packages/core/src/SegmentedControl/XDSSegmentedControlContext.ts
@@ -0,0 +1,35 @@
+/**
+ * @file XDSSegmentedControlContext.ts
+ * @input React createContext, useContext
+ * @output Exports XDSSegmentedControlContext, useXDSSegmentedControlContext
+ * @position Context provider; consumed by XDSSegmentedControlItem.tsx
+ *
+ * SYNC: When modified, update /packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+ */
+
+'use client';
+
+import {createContext, useContext} from 'react';
+
+export type XDSSegmentedControlSize = 'sm' | 'md' | 'lg';
+
+export interface XDSSegmentedControlContextValue {
+ value: string;
+ onChange: (value: string) => void;
+ size: XDSSegmentedControlSize;
+ isDisabled: boolean;
+}
+
+export const XDSSegmentedControlContext =
+ createContext<XDSSegmentedControlContextValue | null>(null);
+
+export function useXDSSegmentedControlContext(): XDSSegmentedControlContextValue {
+ const ctx = useContext(XDSSegmentedControlContext);
+ if (ctx == null) {
+ throw new Error(
+ 'useXDSSegmentedControlContext must be used within XDSSegmentedControl. ' +
+ 'Wrap your XDSSegmentedControlItem in <XDSSegmentedControl>.',
+ );
+ }
+ return ctx;
+}
diff --git a/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsx b/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsx
new file mode 100644
index 0000000000..f1d6020908
--- /dev/null
+++ b/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsx
@@ -0,0 +1,204 @@
+/**
+ * @file XDSSegmentedControlItem.tsx
+ * @input Uses React, StyleX, XDSSegmentedControlContext
+ * @output Exports XDSSegmentedControlItem component and XDSSegmentedControlItemProps type
+ * @position Child item; renders as a radio button within the segmented control
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+ * - /packages/core/src/SegmentedControl/index.ts
+ * - /packages/core/src/SegmentedControl/XDSSegmentedControl.test.tsx
+ */
+
+'use client';
+
+import {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ sizeVars,
+ durationVars,
+ easeVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+ shadowVars,
+} from '../theme/tokens.stylex';
+import {useXDSSegmentedControlContext} from './XDSSegmentedControlContext';
+import type {XDSSegmentedControlSize} from './XDSSegmentedControlContext';
+import {xdsClassName, mergeProps} from '../utils';
+
+export interface XDSSegmentedControlItemProps {
+ /**
+ * Unique value for this segment. Matched against the parent's value.
+ */
+ value: string;
+ /**
+ * Accessible label for this segment (required for accessibility).
+ * Used as visible text, or as aria-label when isLabelHidden is true.
+ */
+ label: string;
+ /**
+ * Whether the label is visually hidden. When true, only the icon is
+ * displayed and the label is used as aria-label for accessibility.
+ * @default false
+ */
+ isLabelHidden?: boolean;
+ /**
+ * Icon element displayed before the label.
+ */
+ icon?: ReactNode;
+ /**
+ * Whether this individual item is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+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',
+ fontFamily: 'inherit',
+ fontSize: textSizeVars['--text-base'],
+ lineHeight: lineHeightVars['--leading-base'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ color: colorVars['--color-text-secondary'],
+ cursor: 'pointer',
+ transitionProperty: 'color, background-color, box-shadow',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ outline: {
+ default: null,
+ ':focus-visible': `2px solid ${colorVars['--color-ring-focus']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
+ },
+ },
+ hover: {
+ backgroundColor: {
+ default: null,
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-overlay-hover'],
+ },
+ },
+ },
+ selected: {
+ color: colorVars['--color-text-primary'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ backgroundColor: colorVars['--color-surface'],
+ boxShadow: shadowVars['--shadow-base'],
+ },
+ disabled: {
+ cursor: 'default',
+ color: colorVars['--color-text-disabled'],
+ },
+ icon: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ flexShrink: 0,
+ },
+});
+
+const CONCENTRIC_RADIUS =
+ 'max(0px, calc(var(--segmented-radius) - var(--segmented-padding)))';
+
+const sizeStyles = stylex.create({
+ sm: {
+ height: `calc(${sizeVars['--size-sm']} - 4px)`,
+ borderRadius: CONCENTRIC_RADIUS,
+ paddingInline: spacingVars['--spacing-2'],
+ fontSize: textSizeVars['--text-sm'],
+ },
+ md: {
+ height: `calc(${sizeVars['--size-md']} - 4px)`,
+ borderRadius: CONCENTRIC_RADIUS,
+ paddingInline: spacingVars['--spacing-3'],
+ },
+ lg: {
+ height: `calc(${sizeVars['--size-lg']} - 4px)`,
+ borderRadius: CONCENTRIC_RADIUS,
+ paddingInline: spacingVars['--spacing-3'],
+ },
+});
+
+const iconSizeStyles = stylex.create({
+ sm: {width: '14px', height: '14px'},
+ md: {width: '16px', height: '16px'},
+ lg: {width: '18px', height: '18px'},
+});
+
+/**
+ * Individual segment item within an XDSSegmentedControl.
+ * Renders as a radio button with visual segment styling.
+ *
+ * @example
+ * ```
+ * <XDSSegmentedControlItem value="grid" label="Grid" icon={<GridIcon />} />
+ * ```
+ */
+export function XDSSegmentedControlItem({
+ value,
+ label,
+ isLabelHidden = false,
+ icon,
+ isDisabled = false,
+}: XDSSegmentedControlItemProps) {
+ const ctx = useXDSSegmentedControlContext();
+
+ const isSelected = ctx.value === value;
+ const isItemDisabled = isDisabled || ctx.isDisabled;
+ const size: XDSSegmentedControlSize = ctx.size;
+
+ const handleClick = useCallback(() => {
+ if (!isItemDisabled && !isSelected) {
+ ctx.onChange(value);
+ }
+ }, [ctx, value, isItemDisabled, isSelected]);
+
+ const iconElement = icon ? (
+ <span {...stylex.props(styles.icon, iconSizeStyles[size])}>{icon}</span>
+ ) : null;
+
+ return (
+ <button
+ type="button"
+ role="radio"
+ aria-checked={isSelected}
+ aria-disabled={isItemDisabled || undefined}
+ aria-label={isLabelHidden ? label : undefined}
+ data-value={value}
+ tabIndex={isSelected ? 0 : -1}
+ onClick={handleClick}
+ {...mergeProps(
+ xdsClassName('segmented-control-item'),
+ stylex.props(
+ styles.base,
+ sizeStyles[size],
+ isSelected && styles.selected,
+ !isSelected && !isItemDisabled && styles.hover,
+ isItemDisabled && styles.disabled,
+ ),
+ )}>
+ {iconElement}
+ {!isLabelHidden && <span>{label}</span>}
+ </button>
+ );
+}
+
+XDSSegmentedControlItem.displayName = 'XDSSegmentedControlItem';
diff --git a/packages/core/src/SegmentedControl/index.ts b/packages/core/src/SegmentedControl/index.ts
new file mode 100644
index 0000000000..ecfae1d785
--- /dev/null
+++ b/packages/core/src/SegmentedControl/index.ts
@@ -0,0 +1,16 @@
+/**
+ * @file index.ts
+ * @input Imports from SegmentedControl component files
+ * @output Exports XDSSegmentedControl, XDSSegmentedControlItem and their types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+ */
+
+export {XDSSegmentedControl} from './XDSSegmentedControl';
+export type {XDSSegmentedControlProps} from './XDSSegmentedControl';
+
+export {XDSSegmentedControlItem} from './XDSSegmentedControlItem';
+export type {XDSSegmentedControlItemProps} from './XDSSegmentedControlItem';
+
+export type {XDSSegmentedControlSize} from './XDSSegmentedControlContext';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 7f02ba4093..5e43edaa61 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -37,6 +37,7 @@ export * from './Field';
export * from './FormLayout';
export * from './Grid';
export * from './Section';
+export * from './SegmentedControl';
export * from './Selector';
export * from './Icon';
export * from './Text';