Skip to content

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

TypeScript

feat(Stepper): add XDSStepper and XDSStep components (#2206)

Andrey Godere65657dd1e9f
diff --git a/apps/storybook/stories/Stepper.stories.tsx b/apps/storybook/stories/Stepper.stories.tsx
new file mode 100644
index 0000000000..d8f9da86b4
--- /dev/null
+++ b/apps/storybook/stories/Stepper.stories.tsx
@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSStepper, XDSStep} from '@xds/core/Stepper';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSButton} from '@xds/core/Button';
+import {XDSText} from '@xds/core/Text';
+
+const meta: Meta<typeof XDSStepper> = {
+ title: 'Core/Navigation/Stepper',
+ component: XDSStepper,
+ tags: ['autodocs'],
+ argTypes: {
+ activeStep: {
+ control: {type: 'number', min: 0, max: 4},
+ description: 'Zero-based index of the active step',
+ },
+ orientation: {
+ control: 'select',
+ options: ['horizontal', 'vertical'],
+ description: 'Layout direction',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSStepper>;
+
+export const Default: Story = {
+ args: {activeStep: 1},
+ render: args => (
+ <XDSStepper activeStep={args.activeStep} orientation={args.orientation}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Review" />
+ </XDSStepper>
+ ),
+};
+
+export const AllCompleted: Story = {
+ render: () => (
+ <XDSStepper activeStep={3}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Review" />
+ </XDSStepper>
+ ),
+};
+
+export const FirstStep: Story = {
+ render: () => (
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Review" />
+ </XDSStepper>
+ ),
+};
+
+export const WithDescriptions: Story = {
+ render: () => (
+ <XDSStepper activeStep={1}>
+ <XDSStep step={0} label="Account" description="Create your account" />
+ <XDSStep step={1} label="Profile" description="Set up your profile" />
+ <XDSStep step={2} label="Review" description="Review and confirm" />
+ </XDSStepper>
+ ),
+};
+
+export const Vertical: Story = {
+ render: () => (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper activeStep={1} orientation="vertical">
+ <XDSStep step={0} label="Account" description="Create your account" />
+ <XDSStep step={1} label="Profile" description="Set up your profile" />
+ <XDSStep step={2} label="Review" description="Review and confirm" />
+ </XDSStepper>
+ </div>
+ ),
+};
+
+export const NonLinear: Story = {
+ name: 'Non-Linear (Clickable)',
+ render: () => {
+ const [activeStep, setActiveStep] = useState(1);
+ return (
+ <XDSStepper activeStep={activeStep} onStepClick={setActiveStep}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Review" />
+ </XDSStepper>
+ );
+ },
+};
+
+export const WithError: Story = {
+ render: () => (
+ <XDSStepper activeStep={1}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" hasError />
+ <XDSStep step={2} label="Review" />
+ </XDSStepper>
+ ),
+};
+
+export const WithDisabled: Story = {
+ render: () => (
+ <XDSStepper activeStep={1}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Review" isDisabled />
+ </XDSStepper>
+ ),
+};
+
+export const FiveSteps: Story = {
+ render: () => (
+ <XDSStepper activeStep={2}>
+ <XDSStep step={0} label="Cart" />
+ <XDSStep step={1} label="Shipping" />
+ <XDSStep step={2} label="Payment" />
+ <XDSStep step={3} label="Review" />
+ <XDSStep step={4} label="Confirm" />
+ </XDSStepper>
+ ),
+};
+
+export const VerticalNonLinear: Story = {
+ name: 'Vertical Non-Linear',
+ render: () => {
+ const [activeStep, setActiveStep] = useState(2);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={activeStep}
+ orientation="vertical"
+ onStepClick={setActiveStep}>
+ <XDSStep step={0} label="Account" description="Create your account" />
+ <XDSStep step={1} label="Profile" description="Set up your profile" />
+ <XDSStep step={2} label="Review" description="Review and confirm" />
+ <XDSStep step={3} label="Done" description="All finished!" />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+export const VerticalWithContent: Story = {
+ name: 'Vertical with Content',
+ render: () => {
+ const [activeStep, setActiveStep] = useState(1);
+ return (
+ <div style={{maxWidth: 480}}>
+ <XDSStepper activeStep={activeStep} orientation="vertical">
+ <XDSStep step={0} label="Account" description="Create your account">
+ {activeStep === 0 && (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <XDSTextInput label="Email" placeholder="[email protected]" />
+ <XDSTextInput label="Password" placeholder="••••••••" />
+ <div>
+ <XDSButton
+ label="Continue"
+ variant="primary"
+ onClick={() => setActiveStep(1)}
+ />
+ </div>
+ </div>
+ )}
+ </XDSStep>
+ <XDSStep
+ step={1}
+ label="Profile"
+ description="Tell us about yourself">
+ {activeStep === 1 && (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <XDSTextInput label="Full name" placeholder="Jane Doe" />
+ <XDSTextInput label="Company" placeholder="Acme Inc." />
+ <XDSTextInput label="Role" placeholder="Engineer" />
+ <div style={{display: 'flex', gap: 8}}>
+ <XDSButton
+ label="Back"
+ variant="secondary"
+ onClick={() => setActiveStep(0)}
+ />
+ <XDSButton
+ label="Continue"
+ variant="primary"
+ onClick={() => setActiveStep(2)}
+ />
+ </div>
+ </div>
+ )}
+ </XDSStep>
+ <XDSStep step={2} label="Review" description="Confirm your details">
+ {activeStep === 2 && (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <XDSText type="body">
+ Review your account details and click Finish to complete
+ setup.
+ </XDSText>
+ <div style={{display: 'flex', gap: 8}}>
+ <XDSButton
+ label="Back"
+ variant="secondary"
+ onClick={() => setActiveStep(1)}
+ />
+ <XDSButton
+ label="Finish"
+ variant="primary"
+ onClick={() => setActiveStep(3)}
+ />
+ </div>
+ </div>
+ )}
+ </XDSStep>
+ </XDSStepper>
+ </div>
+ );
+ },
+};
diff --git a/packages/cli/templates/blocks/components/Stepper/StepperShowcase.doc.mjs b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.doc.mjs
new file mode 100644
index 0000000000..a1629be469
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.doc.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Stepper',
+ name: 'Stepper',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ isShowcase: true,
+ description: 'A horizontal stepper with three steps, the second step active.',
+ componentsUsed: ['Stepper'],
+};
diff --git a/packages/cli/templates/blocks/components/Stepper/StepperShowcase.tsx b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.tsx
new file mode 100644
index 0000000000..20dd854983
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.tsx
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSStepper, XDSStep} from '@xds/core/Stepper';
+
+export default function StepperShowcase() {
+ return (
+ <XDSStepper activeStep={1}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Review" />
+ </XDSStepper>
+ );
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index 4ef970919d..3be722a29e 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -481,6 +481,12 @@
"import": "./dist/StatusDot/index.mjs",
"require": "./dist/StatusDot/index.js"
},
+ "./Stepper": {
+ "source": "./src/Stepper/index.ts",
+ "types": "./dist/Stepper/index.d.ts",
+ "import": "./dist/Stepper/index.mjs",
+ "require": "./dist/Stepper/index.js"
+ },
"./Switch": {
"source": "./src/Switch/index.ts",
"types": "./dist/Switch/index.d.ts",
diff --git a/packages/core/src/Stepper/Stepper.doc.mjs b/packages/core/src/Stepper/Stepper.doc.mjs
new file mode 100644
index 0000000000..6b025fcc34
--- /dev/null
+++ b/packages/core/src/Stepper/Stepper.doc.mjs
@@ -0,0 +1,227 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Stepper',
+ group: 'Stepper',
+ keywords: ['stepper', 'steps', 'wizard', 'workflow', 'progress', 'multi-step', 'form wizard', 'onboarding'],
+ usage: {
+ description:
+ 'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead.',
+ bestPractices: [
+ {guidance: true, description: 'Keep step labels short and descriptive — "Payment" not "Enter your payment information".'},
+ {guidance: true, description: 'Use the vertical orientation for narrow containers or when steps have longer descriptions.'},
+ {guidance: true, description: 'Provide onStepClick for non-linear workflows where users may need to revisit earlier steps.'},
+ {guidance: false, description: 'Use a stepper for fewer than 3 steps — a simple heading or progress bar works better.'},
+ {guidance: false, description: 'Use more than 7 steps — consider grouping related steps or using a different pattern.'},
+ ],
+ anatomy: [
+ {name: 'Step indicator', required: true, description: 'A numbered circle showing the step position. Shows a checkmark when completed.'},
+ {name: 'Connector', required: true, description: 'A line between step indicators. Filled when the preceding step is completed.'},
+ {name: 'Label', required: true, description: 'Text identifying the step.'},
+ {name: 'Description', required: false, description: 'Supporting text below the label with additional context.'},
+ ],
+ },
+ theming: {
+ targets: [
+ {className: 'xds-stepper', visualProps: ['orientation']},
+ {className: 'xds-step', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
+ {className: 'xds-step-indicator', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
+ {className: 'xds-step-connector'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSStepper',
+ description:
+ 'Container component that manages step state and renders steps in horizontal or vertical orientation.',
+ props: [
+ {
+ name: 'activeStep',
+ type: 'number',
+ description: 'Zero-based index of the currently active step. Steps before this index are marked as completed.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSStep elements to render in the stepper.',
+ required: true,
+ },
+ {
+ name: 'orientation',
+ type: "'horizontal' | 'vertical'",
+ description: 'Layout direction of the stepper.',
+ default: "'horizontal'",
+ },
+ {
+ name: 'onStepClick',
+ type: '(index: number) => void',
+ description: 'Called when a step indicator is clicked. Enables non-linear navigation. Completed and active steps become clickable.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the stepper navigation landmark.',
+ default: "'Progress'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+ },
+ {
+ name: 'XDSStep',
+ description:
+ 'Individual step within a stepper. Renders a numbered indicator, connector line, and label with optional description.',
+ props: [
+ {
+ name: 'step',
+ type: 'number',
+ description: 'Zero-based index of this step. Used to determine active/completed state relative to the parent activeStep.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Step label text displayed below (horizontal) or beside (vertical) the indicator.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Optional description shown below the label for additional context.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content rendered below the label and description. Useful in vertical steppers for form fields or detailed step content.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Custom icon to replace the step number or checkmark indicator.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ },
+ {
+ name: 'isCompleted',
+ type: 'boolean',
+ description: 'Override the auto-computed completed state. By default, steps before activeStep are completed.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables interaction and dims the step indicator and label.',
+ default: 'false',
+ },
+ {
+ name: 'hasError',
+ type: 'boolean',
+ description: 'Shows an error state on the step indicator and label.',
+ default: 'false',
+ },
+ ],
+ },
+ ],
+ playground: {
+ defaults: {
+ activeStep: 1,
+ },
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'numbered step sequence for multi-step workflows',
+ usage: {
+ description:
+ 'Steppers show progress through numbered steps. Use for forms, onboarding, checkout.',
+ bestPractices: [
+ {guidance: true, description: 'Keep step labels short. Use vertical in narrow containers.'},
+ {guidance: true, description: 'Provide onStepClick for non-linear workflows.'},
+ {guidance: false, description: 'Use for fewer than 3 or more than 7 steps.'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSStepper',
+ description: 'container managing step state w/ horizontal/vertical layout',
+ propDescriptions: {
+ activeStep: 'zero-based active step index',
+ children: 'XDSStep elements',
+ orientation: 'horizontal or vertical layout',
+ onStepClick: 'enables non-linear navigation',
+ label: 'nav landmark aria-label',
+ xstyle: 'StyleX layout customization',
+ },
+ },
+ {
+ name: 'XDSStep',
+ description: 'individual step w/ indicator, connector, label',
+ propDescriptions: {
+ step: 'zero-based step index',
+ label: 'step label text',
+ description: 'supporting text below label',
+ icon: 'custom icon replacing number/check',
+ isCompleted: 'override auto-completed state',
+ isDisabled: 'disable interaction',
+ hasError: 'error state on indicator and label',
+ },
+ },
+ ],
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+ name: 'Stepper',
+ group: 'Stepper',
+ usage: {
+ description:
+ '步骤器显示通过一系列逻辑编号步骤的进度。用于多步骤工作流程,如表单、入职流程或结账流程。',
+ bestPractices: [
+ {guidance: true, description: '保持步骤标签简短和描述性。'},
+ {guidance: true, description: '在窄容器中使用垂直方向,或当步骤有较长描述时。'},
+ {guidance: true, description: '为非线性工作流程提供 onStepClick。'},
+ {guidance: false, description: '少于3个步骤时使用步骤器。'},
+ {guidance: false, description: '超过7个步骤时使用步骤器。'},
+ ],
+ },
+ theming: {
+ targets: [
+ {className: 'xds-stepper', visualProps: ['orientation']},
+ {className: 'xds-step', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
+ {className: 'xds-step-indicator', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
+ {className: 'xds-step-connector'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSStepper',
+ description: '容器组件,管理步骤状态并以水平或垂直方向渲染步骤。',
+ props: [
+ {name: 'activeStep', type: 'number', description: '当前活动步骤的从零开始的索引。', required: true},
+ {name: 'children', type: 'ReactNode', description: '要在步骤器中渲染的 XDSStep 元素。', required: true},
+ {name: 'orientation', type: "'horizontal' | 'vertical'", description: '步骤器的布局方向。', default: "'horizontal'"},
+ {name: 'onStepClick', type: '(index: number) => void', description: '点击步骤指示器时调用。启用非线性导航。'},
+ {name: 'label', type: 'string', description: '步骤器导航地标的无障碍标签。', default: "'Progress'"},
+ {name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。'},
+ ],
+ },
+ {
+ name: 'XDSStep',
+ description: '步骤器中的单个步骤。渲染编号指示器、连接线和带可选描述的标签。',
+ props: [
+ {name: 'step', type: 'number', description: '此步骤的从零开始的索引。', required: true},
+ {name: 'label', type: 'string', description: '步骤标签文本。', required: true},
+ {name: 'description', type: 'string', description: '标签下方的可选描述。'},
+ {name: 'icon', type: 'ReactNode', description: '替换步骤编号或勾选指示器的自定义图标。'},
+ {name: 'isCompleted', type: 'boolean', description: '覆盖自动计算的完成状态。'},
+ {name: 'isDisabled', type: 'boolean', description: '禁用交互并使步骤指示器和标签变暗。', default: 'false'},
+ {name: 'hasError', type: 'boolean', description: '在步骤指示器和标签上显示错误状态。', default: 'false'},
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Stepper/XDSStep.tsx b/packages/core/src/Stepper/XDSStep.tsx
new file mode 100644
index 0000000000..7d1c2a66e6
--- /dev/null
+++ b/packages/core/src/Stepper/XDSStep.tsx
@@ -0,0 +1,496 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSStep.tsx
+ * @input Uses React, stylex, theme tokens, XDSStepperContext
+ * @output Exports XDSStep component and XDSStepProps
+ * @position Individual step item; used inside XDSStepper
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs
+ * - /packages/core/src/Stepper/XDSStepper.test.tsx
+ * - /packages/core/src/Stepper/index.ts
+ * - /apps/storybook/stories/Stepper.stories.tsx
+ * - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ fontWeightVars,
+ typeScaleVars,
+ durationVars,
+ easeVars,
+} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
+import {XDSIcon} from '../Icon';
+import type {XDSBaseProps} from '../XDSBaseProps';
+import {useXDSStepperContext} from './XDSStepperContext';
+
+export interface XDSStepProps extends XDSBaseProps<HTMLDivElement> {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+ /**
+ * Zero-based index of this step. Used to determine active/completed state
+ * relative to the parent's activeStep.
+ */
+ step: number;
+ /**
+ * Step label text.
+ */
+ label: string;
+ /**
+ * Optional description shown below the label.
+ */
+ description?: string;
+ /**
+ * Content rendered below the label and description. Useful in vertical
+ * steppers to show form fields or detailed content for each step.
+ */
+ children?: ReactNode;
+ /**
+ * Custom icon to replace the step number/check indicator.
+ */
+ icon?: ReactNode;
+ /**
+ * Override the auto-computed completed state.
+ * By default, steps before activeStep are completed.
+ */
+ isCompleted?: boolean;
+ /**
+ * Disable interaction for this step.
+ * @default false
+ */
+ isDisabled?: boolean;
+ /**
+ * Optional error state for this step.
+ * @default false
+ */
+ hasError?: boolean;
+}
+
+const styles = stylex.create({
+ // Horizontal layout
+ horizontalRoot: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'flex-start',
+ flex: {
+ default: 1,
+ ':last-child': 'none',
+ },
+ '--_show-connector': {
+ default: 'flex',
+ ':last-child': 'none',
+ },
+ position: 'relative',
+ },
+ horizontalContent: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ position: 'relative',
+ zIndex: 1,
+ },
+ horizontalConnector: {
+ flex: 1,
+ display: 'var(--_show-connector)',
+ alignItems: 'center',
+ paddingInline: spacingVars['--spacing-2'],
+ minWidth: spacingVars['--spacing-6'],
+ height: spacingVars['--spacing-7'],
+ },
+ horizontalConnectorLine: {
+ height: spacingVars['--spacing-0-5'],
+ width: '100%',
+ borderRadius: radiusVars['--radius-full'],
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+
+ // Vertical layout
+ verticalRoot: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'stretch',
+ position: 'relative',
+ minHeight: spacingVars['--spacing-12'],
+ '--_show-connector': {
+ default: 'flex',
+ ':last-child': 'none',
+ },
+ },
+ verticalIndicatorColumn: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ width: spacingVars['--spacing-7'],
+ flexShrink: 0,
+ },
+ verticalConnector: {
+ flex: 1,
+ display: 'var(--_show-connector)',
+ justifyContent: 'center',
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ verticalConnectorLine: {
+ width: spacingVars['--spacing-0-5'],
+ height: '100%',
+ borderRadius: radiusVars['--radius-full'],
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ verticalContent: {
+ display: 'flex',
+ flexDirection: 'column',
+ paddingInlineStart: spacingVars['--spacing-3'],
+ paddingBlockEnd: spacingVars['--spacing-6'],
+ flex: 1,
+ },
+ verticalLastContent: {
+ paddingBlockEnd: spacingVars['--spacing-0'],
+ },
+
+ // Indicator circle
+ indicator: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: spacingVars['--spacing-7'],
+ height: spacingVars['--spacing-7'],
+ borderRadius: radiusVars['--radius-full'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ transitionProperty: 'background-color, color, border-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ flexShrink: 0,
+ userSelect: 'none',
+ borderWidth: spacingVars['--spacing-0-5'],
+ borderStyle: 'solid',
+ position: 'relative',
+ },
+ indicatorActive: {
+ backgroundColor: colorVars['--color-accent'],
+ borderColor: colorVars['--color-accent'],
+ color: colorVars['--color-on-accent'],
+ },
+ indicatorCompleted: {
+ backgroundColor: colorVars['--color-accent'],
+ borderColor: colorVars['--color-accent'],
+ color: colorVars['--color-on-accent'],
+ },
+ indicatorUpcoming: {
+ backgroundColor: 'transparent',
+ borderColor: colorVars['--color-border-emphasized'],
+ color: colorVars['--color-text-secondary'],
+ },
+ indicatorDisabled: {
+ backgroundColor: 'transparent',
+ borderColor: colorVars['--color-border'],
+ color: colorVars['--color-text-disabled'],
+ },
+ indicatorError: {
+ backgroundColor: colorVars['--color-error'],
+ borderColor: colorVars['--color-error'],
+ color: colorVars['--color-on-error'],
+ },
+ indicatorClickable: {
+ cursor: 'pointer',
+ ':hover': {
+ '@media (hover: hover)': {
+ opacity: 0.85,
+ },
+ },
+ },
+
+ // Connector line colors
+ connectorCompleted: {
+ backgroundColor: colorVars['--color-accent'],
+ },
+ connectorIncomplete: {
+ backgroundColor: colorVars['--color-border-emphasized'],
+ },
+
+ // Label and description
+ labelRow: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ paddingBlockStart: spacingVars['--spacing-1'],
+ // No spacing token at 120px — nearest are --spacing-12 (48px) and --spacing-14 (56px)
+ maxWidth: '120px',
+ },
+ labelRowVertical: {
+ alignItems: 'flex-start',
+ maxWidth: 'none',
+ paddingBlockStart: spacingVars['--spacing-0-5'],
+ },
+ label: {
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ textAlign: 'center',
+ },
+ labelVertical: {
+ textAlign: 'start',
+ },
+ labelActive: {
+ color: colorVars['--color-text-primary'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ },
+ labelCompleted: {
+ color: colorVars['--color-text-primary'],
+ },
+ labelUpcoming: {
+ color: colorVars['--color-text-secondary'],
+ },
+ labelDisabled: {
+ color: colorVars['--color-text-disabled'],
+ },
+ labelError: {
+ color: colorVars['--color-error'],
+ },
+ description: {
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ color: colorVars['--color-text-secondary'],
+ textAlign: 'center',
+ },
+ descriptionVertical: {
+ textAlign: 'start',
+ },
+ descriptionError: {
+ color: colorVars['--color-error'],
+ },
+
+ // Button reset for clickable indicators
+ buttonReset: {
+ background: 'none',
+ border: 'none',
+ padding: 0,
+ margin: 0,
+ font: 'inherit',
+ },
+
+ // Step content (children)
+ stepContent: {
+ paddingBlockStart: spacingVars['--spacing-3'],
+ },
+});
+
+/**
+ * An individual step within an XDSStepper. Renders a numbered indicator
+ * circle, a connector line to the next step, and a label with optional
+ * description. Step state (active, completed, upcoming) is derived from
+ * the parent's activeStep and this step's `step` prop.
+ *
+ * @example
+ * ```
+ * <XDSStep step={0} label="Account details" description="Enter your email" />
+ * ```
+ */
+export function XDSStep({
+ step,
+ label,
+ description,
+ children,
+ icon,
+ isCompleted: isCompletedProp,
+ isDisabled = false,
+ hasError = false,
+ xstyle,
+ className,
+ style,
+ ref,
+ 'data-testid': dataTestId,
+ ...rest
+}: XDSStepProps) {
+ const ctx = useXDSStepperContext();
+ const {activeStep, orientation, isNonLinear, onStepClick} = ctx;
+
+ const isActive = step === activeStep;
+ const isCompleted = isCompletedProp ?? step < activeStep;
+ const isVertical = orientation === 'vertical';
+
+ const isClickable = isNonLinear && !isDisabled && (isCompleted || isActive);
+
+ const handleClick = () => {
+ if (isClickable && onStepClick) {
+ onStepClick(step);
+ }
+ };
+
+ const indicatorContent = hasError ? (
+ <XDSIcon icon="warning" size="sm" color="inherit" />
+ ) : icon != null ? (
+ icon
+ ) : isCompleted ? (
+ <XDSIcon icon="check" size="sm" color="inherit" />
+ ) : (
+ <span>{step + 1}</span>
+ );
+
+ const indicatorVariantStyle = hasError
+ ? styles.indicatorError
+ : isDisabled
+ ? styles.indicatorDisabled
+ : isActive
+ ? styles.indicatorActive
+ : isCompleted
+ ? styles.indicatorCompleted
+ : styles.indicatorUpcoming;
+
+ const stepState = hasError
+ ? 'error'
+ : isDisabled
+ ? 'disabled'
+ : isActive
+ ? 'active'
+ : isCompleted
+ ? 'completed'
+ : 'upcoming';
+
+ const indicator = isClickable ? (
+ <button
+ type="button"
+ onClick={handleClick}
+ aria-label={`Go to step ${step + 1}: ${label}`}
+ {...mergeProps(
+ xdsClassName('step-indicator', {state: stepState}),
+ stylex.props(
+ styles.buttonReset,
+ styles.indicator,
+ indicatorVariantStyle,
+ styles.indicatorClickable,
+ ),
+ )}>
+ {indicatorContent}
+ </button>
+ ) : (
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ xdsClassName('step-indicator', {state: stepState}),
+ stylex.props(styles.indicator, indicatorVariantStyle),
+ )}>
+ {indicatorContent}
+ </div>
+ );
+
+ const labelNode = (
+ <div
+ {...stylex.props(styles.labelRow, isVertical && styles.labelRowVertical)}>
+ <span
+ {...stylex.props(
+ styles.label,
+ isVertical && styles.labelVertical,
+ hasError
+ ? styles.labelError
+ : isDisabled
+ ? styles.labelDisabled
+ : isActive
+ ? styles.labelActive
+ : isCompleted
+ ? styles.labelCompleted
+ : styles.labelUpcoming,
+ )}>
+ {label}
+ </span>
+ {description != null && (
+ <span
+ {...stylex.props(
+ styles.description,
+ isVertical && styles.descriptionVertical,
+ hasError && styles.descriptionError,
+ )}>
+ {description}
+ </span>
+ )}
+ </div>
+ );
+
+ if (isVertical) {
+ return (
+ <div
+ ref={ref}
+ {...mergeProps(
+ xdsClassName('step', {state: stepState}),
+ stylex.props(styles.verticalRoot, xstyle),
+ className,
+ style,
+ )}
+ aria-current={isActive ? 'step' : undefined}
+ data-testid={dataTestId}
+ role="listitem"
+ {...rest}>
+ <div {...stylex.props(styles.verticalIndicatorColumn)}>
+ {indicator}
+ <div {...stylex.props(styles.verticalConnector)}>
+ <div
+ {...mergeProps(
+ xdsClassName('step-connector'),
+ stylex.props(
+ styles.verticalConnectorLine,
+ isCompleted
+ ? styles.connectorCompleted
+ : styles.connectorIncomplete,
+ ),
+ )}
+ />
+ </div>
+ </div>
+ <div {...stylex.props(styles.verticalContent)}>
+ {labelNode}
+ {children != null && (
+ <div {...stylex.props(styles.stepContent)}>{children}</div>
+ )}
+ </div>
+ </div>
+ );
+ }
+
+ return (
+ <div
+ ref={ref}
+ {...mergeProps(
+ xdsClassName('step', {state: stepState}),
+ stylex.props(styles.horizontalRoot, xstyle),
+ className,
+ style,
+ )}
+ aria-current={isActive ? 'step' : undefined}
+ data-testid={dataTestId}
+ role="listitem"
+ {...rest}>
+ <div {...stylex.props(styles.horizontalContent)}>
+ {indicator}
+ {labelNode}
+ </div>
+ <div {...stylex.props(styles.horizontalConnector)}>
+ <div
+ {...mergeProps(
+ xdsClassName('step-connector'),
+ stylex.props(
+ styles.horizontalConnectorLine,
+ isCompleted
+ ? styles.connectorCompleted
+ : styles.connectorIncomplete,
+ ),
+ )}
+ />
+ </div>
+ </div>
+ );
+}
+
+XDSStep.displayName = 'XDSStep';
diff --git a/packages/core/src/Stepper/XDSStepper.test.tsx b/packages/core/src/Stepper/XDSStepper.test.tsx
new file mode 100644
index 0000000000..ffc2a9e8a9
--- /dev/null
+++ b/packages/core/src/Stepper/XDSStepper.test.tsx
@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSStepper} from './XDSStepper';
+import {XDSStep} from './XDSStep';
+
+describe('XDSStepper', () => {
+ it('renders a navigation landmark with steps', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ expect(
+ screen.getByRole('navigation', {name: 'Progress'}),
+ ).toBeInTheDocument();
+ expect(screen.getByText('Step 1')).toBeInTheDocument();
+ expect(screen.getByText('Step 2')).toBeInTheDocument();
+ expect(screen.getByText('Step 3')).toBeInTheDocument();
+ });
+
+ it('renders step numbers', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="First" />
+ <XDSStep step={1} label="Second" />
+ </XDSStepper>,
+ );
+ expect(screen.getByText('1')).toBeInTheDocument();
+ expect(screen.getByText('2')).toBeInTheDocument();
+ });
+
+ it('marks the active step with aria-current', () => {
+ render(
+ <XDSStepper activeStep={1}>
+ <XDSStep step={0} label="Step 1" data-testid="step-0" />
+ <XDSStep step={1} label="Step 2" data-testid="step-1" />
+ <XDSStep step={2} label="Step 3" data-testid="step-2" />
+ </XDSStepper>,
+ );
+ expect(screen.getByTestId('step-0')).not.toHaveAttribute('aria-current');
+ expect(screen.getByTestId('step-1')).toHaveAttribute(
+ 'aria-current',
+ 'step',
+ );
+ expect(screen.getByTestId('step-2')).not.toHaveAttribute('aria-current');
+ });
+
+ it('renders descriptions when provided', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="Account" description="Create your account" />
+ <XDSStep step={1} label="Profile" />
+ </XDSStepper>,
+ );
+ expect(screen.getByText('Create your account')).toBeInTheDocument();
+ });
+
+ it('supports custom accessible label', () => {
+ render(
+ <XDSStepper activeStep={0} label="Checkout progress">
+ <XDSStep step={0} label="Cart" />
+ <XDSStep step={1} label="Payment" />
+ </XDSStepper>,
+ );
+ expect(
+ screen.getByRole('navigation', {name: 'Checkout progress'}),
+ ).toBeInTheDocument();
+ });
+
+ it('supports vertical orientation', () => {
+ render(
+ <XDSStepper activeStep={0} orientation="vertical">
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ </XDSStepper>,
+ );
+ const nav = screen.getByRole('navigation');
+ expect(nav).toBeInTheDocument();
+ });
+
+ it('calls onStepClick when a completed step is clicked', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <XDSStepper activeStep={2} onStepClick={handleClick}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go to step 1: Step 1'}),
+ );
+ expect(handleClick).toHaveBeenCalledWith(0);
+ });
+
+ it('calls onStepClick when the active step is clicked', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <XDSStepper activeStep={1} onStepClick={handleClick}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go to step 2: Step 2'}),
+ );
+ expect(handleClick).toHaveBeenCalledWith(1);
+ });
+
+ it('does not render buttons for upcoming steps in non-linear mode', () => {
+ render(
+ <XDSStepper activeStep={0} onStepClick={() => {}}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ </XDSStepper>,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Go to step 1: Step 1'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', {name: 'Go to step 2: Step 2'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('does not render buttons for disabled steps', () => {
+ render(
+ <XDSStepper activeStep={2} onStepClick={() => {}}>
+ <XDSStep step={0} label="Step 1" isDisabled />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Go to step 1: Step 1'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('does not render buttons when onStepClick is not provided', () => {
+ render(
+ <XDSStepper activeStep={2}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ expect(screen.queryAllByRole('button')).toHaveLength(0);
+ });
+
+ it('supports isCompleted override', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="Step 1" data-testid="step-0" />
+ <XDSStep step={1} label="Step 2" isCompleted data-testid="step-1" />
+ </XDSStepper>,
+ );
+ const step1 = screen.getByTestId('step-1');
+ expect(step1).toBeInTheDocument();
+ });
+
+ it('handles zero active step correctly', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="Step 1" data-testid="step-0" />
+ <XDSStep step={1} label="Step 2" data-testid="step-1" />
+ </XDSStepper>,
+ );
+ expect(screen.getByTestId('step-0')).toHaveAttribute(
+ 'aria-current',
+ 'step',
+ );
+ expect(screen.getByTestId('step-1')).not.toHaveAttribute('aria-current');
+ });
+
+ it('renders listitem roles for each step', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ expect(screen.getAllByRole('listitem')).toHaveLength(3);
+ });
+});
diff --git a/packages/core/src/Stepper/XDSStepper.tsx b/packages/core/src/Stepper/XDSStepper.tsx
new file mode 100644
index 0000000000..d3ecae3ac5
--- /dev/null
+++ b/packages/core/src/Stepper/XDSStepper.tsx
@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSStepper.tsx
+ * @input Uses React, stylex, theme tokens, XDSStepperContext
+ * @output Exports XDSStepper component and XDSStepperProps
+ * @position Core container component; consumed by index.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Stepper/XDSStepper.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Stepper/index.ts (exports if types change)
+ * - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {xdsClassName, mergeProps} from '../utils';
+import type {XDSBaseProps} from '../XDSBaseProps';
+import {
+ XDSStepperContext,
+ type XDSStepperOrientation,
+ type XDSStepperContextValue,
+} from './XDSStepperContext';
+
+export interface XDSStepperProps extends XDSBaseProps<HTMLDivElement> {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+ /**
+ * Zero-based index of the active step.
+ */
+ activeStep: number;
+ /**
+ * XDSStep elements to render.
+ */
+ children: ReactNode;
+ /**
+ * Layout direction of the stepper.
+ * @default 'horizontal'
+ */
+ orientation?: XDSStepperOrientation;
+ /**
+ * Called when a step indicator is clicked. Enables non-linear navigation.
+ * When provided, completed and current steps become clickable.
+ */
+ onStepClick?: (index: number) => void;
+ /**
+ * Accessible label for the stepper navigation landmark.
+ * @default 'Progress'
+ */
+ label?: string;
+}
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ width: '100%',
+ listStyleType: 'none',
+ margin: 0,
+ padding: 0,
+ },
+ horizontal: {
+ flexDirection: 'row',
+ alignItems: 'flex-start',
+ },
+ vertical: {
+ flexDirection: 'column',
+ },
+});
+
+/**
+ * A stepper component for multi-step workflows. Displays numbered steps
+ * with visual indicators for completed, active, and upcoming states.
+ *
+ * Each XDSStep child must provide a `step` prop (zero-based index) so it
+ * can derive its state from the parent's activeStep. CSS :last-child
+ * handles connector hiding — no child introspection needed.
+ *
+ * @example
+ * ```
+ * <XDSStepper activeStep={1}>
+ * <XDSStep step={0} label="Account" />
+ * <XDSStep step={1} label="Profile" />
+ * <XDSStep step={2} label="Review" />
+ * </XDSStepper>
+ * ```
+ */
+export function XDSStepper({
+ activeStep,
+ children,
+ orientation = 'horizontal',
+ onStepClick,
+ label = 'Progress',
+ xstyle,
+ className,
+ style,
+ ref,
+ ...rest
+}: XDSStepperProps) {
+ const ctxValue = useMemo<XDSStepperContextValue>(
+ () => ({
+ activeStep,
+ orientation,
+ isNonLinear: onStepClick != null,
+ onStepClick: onStepClick ?? null,
+ }),
+ [activeStep, orientation, onStepClick],
+ );
+
+ return (
+ <XDSStepperContext.Provider value={ctxValue}>
+ <nav ref={ref} aria-label={label} {...rest}>
+ <ol
+ {...mergeProps(
+ xdsClassName('stepper', {orientation}),
+ stylex.props(
+ styles.root,
+ orientation === 'horizontal'
+ ? styles.horizontal
+ : styles.vertical,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {children}
+ </ol>
+ </nav>
+ </XDSStepperContext.Provider>
+ );
+}
+
+XDSStepper.displayName = 'XDSStepper';
diff --git a/packages/core/src/Stepper/XDSStepperContext.ts b/packages/core/src/Stepper/XDSStepperContext.ts
new file mode 100644
index 0000000000..ec6bdb06b1
--- /dev/null
+++ b/packages/core/src/Stepper/XDSStepperContext.ts
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSStepperContext.ts
+ * @input Uses React createContext/useContext
+ * @output Exports XDSStepperContext, useXDSStepperContext, and context types
+ * @position Context for XDSStepper <-> XDSStep communication
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs
+ * - /packages/core/src/Stepper/index.ts
+ */
+
+import {createContext, useContext} from 'react';
+
+export type XDSStepperOrientation = 'horizontal' | 'vertical';
+
+export interface XDSStepperContextValue {
+ activeStep: number;
+ orientation: XDSStepperOrientation;
+ isNonLinear: boolean;
+ onStepClick: ((index: number) => void) | null;
+}
+
+export const XDSStepperContext = createContext<XDSStepperContextValue | null>(
+ null,
+);
+
+export function useXDSStepperContext(): XDSStepperContextValue {
+ const ctx = useContext(XDSStepperContext);
+ if (ctx == null) {
+ throw new Error(
+ 'useXDSStepperContext must be used within XDSStepper. ' +
+ 'Wrap your XDSStep in <XDSStepper>.',
+ );
+ }
+ return ctx;
+}
diff --git a/packages/core/src/Stepper/index.ts b/packages/core/src/Stepper/index.ts
new file mode 100644
index 0000000000..dd40cc2300
--- /dev/null
+++ b/packages/core/src/Stepper/index.ts
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from Stepper component files
+ * @output Exports XDSStepper, XDSStep 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/Stepper/Stepper.doc.mjs
+ */
+
+export {XDSStepper} from './XDSStepper';
+export type {XDSStepperProps} from './XDSStepper';
+
+export {XDSStep} from './XDSStep';
+export type {XDSStepProps} from './XDSStep';
+
+export {useXDSStepperContext} from './XDSStepperContext';
+export type {XDSStepperOrientation} from './XDSStepperContext';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 8e03e29c90..6e6fa28244 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -93,6 +93,7 @@ export * from './SideNav';
export * from './MobileNav';
export * from './Pagination';
export * from './ProgressBar';
+export * from './Stepper';
// Layout utilities and components (includes XDSHStack, XDSVStack)
export * from './Layout';