[Stepper] Improve accessibility by silviuaavram · Pull Request #47687 · mui/material-ui

silviuaavram · 2026-01-27T08:27:12Z

I have followed (at least) the PR section of the contributing guide.

Fixes #43689.
Fixes #32826.

Stepper:

improve markup for stepper and step, from divs to ol and li.
implement roving tabindex focus for the step buttons.
step buttons also receive the role of tab, aria-posinset, aria-setsize and aria-selected instead of aria-current.
stepper that has step buttons will have the role of tablist and aria-orientation
step that has step buttons will have the role of presentation.

Technical:

roving tabindex has a separate hook that keeps track of the current focusable item (by index).
it exports 2 prop getters, one for container, one for item, and a focusNext function
one source of truth for tabindex values -> the hook.
update the Tabs and MenuList to also use the hook instead of their own logic
exported focusNext from the hook, for MenuList to use it for character key focus, in order to keep the single source of truth for the tabindex.
using refs instead of parsing DOM directly for getting the focusable siblings

UX for roving tabindex:

tabindex now follows focus. before, it stayed on the selected item, even as you moved away with arrow keys. this created issues:
- if you tabbed from and back, the previously focused item was forgotten, you would've ended up on the selected item
- if you moved selection from selected item with arrows, then tabbed / shift tabbed, you could have ended up with the selected item focused, which should not have happened

mui-bot · 2026-01-27T08:28:22Z

Netlify deploy preview

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	🔺+1.6KB^(+0.31%)	🔺+668B^(+0.44%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	🔺+1.94KB^(+15.09%)	🔺+753B^(+14.95%)

Details of bundle changes

Generated by 🚫 dangerJS against f10f8b7

Copilot

Pull request overview

This pull request improves the accessibility of the Stepper component by implementing semantic HTML markup and keyboard navigation following ARIA best practices.

Changes:

Replaced div elements with semantic ol/li elements for Stepper and Step components
Implemented roving tabindex focus management with arrow key navigation for step buttons
Added ARIA attributes (aria-posinset, aria-setsize, aria-orientation) to improve screen reader support
Refactored StepperContext to export only useStepperContext hook and StepperContextProvider, removing the default export

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.ts	New hook implementing circular keyboard navigation with arrow keys, skipping disabled steps
packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.test.tsx	Comprehensive unit tests for the roving tabindex hook
packages/mui-material/src/Stepper/index.js	Removed default export of StepperContext, keeping named exports
packages/mui-material/src/Stepper/index.d.ts	Updated TypeScript exports to match JavaScript changes
packages/mui-material/src/Stepper/StepperContext.ts	Added new context properties for focus management, marked as @internal, exported StepperContextProvider
packages/mui-material/src/Stepper/Stepper.test.tsx	Updated test to expect HTMLOListElement instead of HTMLDivElement
packages/mui-material/src/Stepper/Stepper.js	Changed root element from div to ol, integrated roving tabindex, added aria-orientation
packages/mui-material/src/StepLabel/StepLabel.js	Updated to use useStepperContext hook instead of direct context import
packages/mui-material/src/StepContent/StepContent.js	Updated to use useStepperContext hook instead of direct context import
packages/mui-material/src/StepConnector/StepConnector.js	Updated to use useStepperContext hook instead of direct context import
packages/mui-material/src/StepButton/StepButton.test.js	Added StepperContextProvider wrapper to all test cases
packages/mui-material/src/StepButton/StepButton.js	Integrated roving tabindex, added ARIA attributes, implemented keyboard and click handlers
packages/mui-material/src/StepButton/StepButton.d.ts	Added TypeScript definitions for onClick and onKeyDown props
packages/mui-material/src/Step/Step.test.js	Updated tests for li element and added StepperContextProvider wrappers
packages/mui-material/src/Step/Step.js	Changed root element from div to li, updated to use useStepperContext hook

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.test.tsx

packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.ts

packages/mui-material/src/Stepper/Stepper.js

packages/mui-material/src/Stepper/StepperContext.ts

packages/mui-material/src/Stepper/Stepper.js

packages/mui-material/src/Stepper/StepperContext.ts

packages/mui-material/src/StepButton/StepButton.js

packages/mui-material/src/Stepper/Stepper.js

packages/mui-material/src/StepButton/StepButton.js

ZeeshanTamboli

@silviuaavram Tested it initially with NVDA screen reader. Nice improvements.

With NVDA enabled, the Left/Right arrow keys don't work on the non-linear stepper:
https://deploy-preview-47687--material-ui.netlify.app/material-ui/react-stepper/#non-linear and nothing is announced as well. When NVDA is off, arrow-key navigation works as expected.
Is it expected that Tab key should move focus to the next step? Since this isn't a tablist, I'm not sure. On the docs site (https://mui.com/material-ui/react-stepper/#non-linear), Tab moves between steps, but in this PR it jumps directly to the "Next" button.
If useStepperContext is intended to be a public API, I think we should document how to use it with a custom stepper demo.

silviuaavram · 2026-02-02T09:02:49Z

Hey @ZeeshanTamboli thanks for your input!

I don't know what to say, especially that I don't have a windows setup at the moment. For example, does this stepper work with NVDA?
I expect Tab to only work on one step at a time. Focusing other steppers with keyboard should work with arrows instead.
useStepperContext should not be public, as StepperContext wasn't public either, right? The hook is meant be used internally, instead of doing useContext(StepperContext).

ZeeshanTamboli · 2026-02-02T12:40:58Z

Hey @ZeeshanTamboli thanks for your input!

I don't know what to say, especially that I don't have a windows setup at the moment. For example, does this stepper work with NVDA?

Yes, it works. I am able to navigate with left/right arrow keys with NVDA enabled in this demo but not in this PR's demo.

I expect Tab to only work on one step at a time. Focusing other steppers with keyboard should work with arrows instead.

Ok, so you mean, pressing Tab should focus only on the last focused step in the Stepper and not move to the next step like in production?

useStepperContext should not be public, as StepperContext wasn't public either, right? The hook is meant be used internally, instead of doing useContext(StepperContext).

I read this only export useStepperContext in order to control the usage better. in the PR description, so I thought it is exported.

packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.ts

Copilot

Pull request overview

Copilot reviewed 30 out of 32 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T15:17:55Z

packages/mui-utils/src/useRovingTabIndex/useRovingTabIndex.ts

+        ref(node);
+      } else if (ref) {
+        ref.current = node;
+      }
+    });


handleRefs assigns to ref.current, but React.RefObject has a readonly current in the React type definitions (e.g. refs created via createRef()), which will cause a TypeScript error here. Use a safe ref setter helper (like MUI's setRef/useForkRef pattern) or narrow to MutableRefObject before assignment to keep this hook type-safe.

Copilot · 2026-03-10T15:17:55Z

packages/mui-material/src/Stepper/index.js

@@ -3,5 +3,4 @@ export { default } from './Stepper';
 export { default as stepperClasses } from './stepperClasses';
 export * from './stepperClasses';



StepperContext was previously re-exported from the Stepper entrypoint, but this change removes the named export (export { default as StepperContext } ...) while keeping only export *. Since export * does not re-export the default, this is a breaking public API change for anyone importing { StepperContext } from @mui/material/Stepper. If the removal is intentional for v9, it should be called out in the v9 migration notes; otherwise consider keeping the named export for compatibility.

Suggested change

export { default as StepperContext } from './StepperContext';

Copilot · 2026-03-10T15:17:56Z

packages/mui-material/src/Stepper/Stepper.js

        className={clsx(classes.root, className)}
        ref={ref}
+        {...(isTabList && {
+          role: 'tablist',
+          'aria-orientation': orientation,


StepperRoot receives ref={ref} but when isTabList is true the spread of rovingTabIndexContainerProps includes its own ref, which will override the forwarded ref. This breaks ref forwarding for <Stepper /> in the tablist case. Merge refs (e.g. via useForkRef) so only one ref is ultimately passed to StepperRoot.

Copilot · 2026-03-10T15:17:56Z

packages/mui-material/src/MenuList/MenuList.js

+  const { focusNext, getContainerProps, getItemProps } = useRovingTabIndex({
+    focusableIndex: activeItemIndex,


activeItemIndex is computed as the raw child index (including muiSkipListHighlight items like Divider/ListSubheader), but getItemProps() is called with a separate focusableIndex counter that skips those items. Passing focusableIndex: activeItemIndex into useRovingTabIndex can desync the roving state from the registered elements, leading to incorrect initial tabbable item when there are skipped/presentation children before the active item. Compute and pass a focusable-item index that uses the same skipping rules as the render loop (or maintain a mapping from child index to focusable index).

Suggested change

const { focusNext, getContainerProps, getItemProps } = useRovingTabIndex({

focusableIndex: activeItemIndex,

// Map the raw child index `activeItemIndex` to the corresponding focusable index

// used by useRovingTabIndex (which skips muiSkipListHighlight items).

let focusableActiveItemIndex = -1;

if (activeItemIndex !== -1) {

let currentFocusableIndex = 0;

React.Children.forEach(children, (child, index) => {

if (

React.isValidElement(child) &&

!child.props.muiSkipListHighlight &&

!child.type.muiSkipListHighlight

) {

if (index === activeItemIndex && !child.props.disabled) {

focusableActiveItemIndex = currentFocusableIndex;

}

currentFocusableIndex += 1;

}

});

}

const { focusNext, getContainerProps, getItemProps } = useRovingTabIndex({

focusableIndex: focusableActiveItemIndex,

Copilot · 2026-03-10T15:17:57Z

packages/mui-utils/src/useRovingTabIndex/useRovingTabIndex.ts

+  getItemProps: (
+    index: number,
+    ref?: React.RefObject<HTMLElement>,
+  ) => {
+    ref: (element: HTMLElement | null) => void;


The exported UseRovingTabIndexReturn.getItemProps type only accepts ref?: React.RefObject<HTMLElement>, but the implementation supports general React.Ref<HTMLElement> and callers may supply callback refs (e.g. child.ref). Widen the type to React.Ref<HTMLElement> to match usage and avoid TypeScript errors for callback refs.

Copilot · 2026-03-10T15:17:57Z

packages/mui-utils/src/useRovingTabIndex/useRovingTabIndex.ts

+  if (
+    focusableIndexProp !== undefined &&
+    focusableIndexProp !== previousFocusableIndexPropRef.current
+  ) {
+    previousFocusableIndexPropRef.current = focusableIndexProp;


The hook calls setFocusableIndex during render when focusableIndexProp changes. Updating state during render can trigger React warnings and is not concurrent/StrictMode-friendly. Sync the controlled focusableIndexProp via useEffect (or the existing useControlled utility) instead of performing a state update inside the render path.

Copilot AI review requested due to automatic review settings January 27, 2026 08:27

Copilot started reviewing on behalf of silviuaavram January 27, 2026 08:28 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

silviuaavram marked this pull request as draft January 27, 2026 08:41

silviuaavram mentioned this pull request Jan 27, 2026

[Stepper] Lacks accessibility #43689

Open

silviuaavram force-pushed the feat/stepper-accessibility branch from 2efcaec to a84bfad Compare January 27, 2026 17:44

silviuaavram marked this pull request as ready for review January 27, 2026 17:56

silviuaavram mentioned this pull request Jan 28, 2026

Accessibility | Narrator is not announcing the Stepper headings as "selected" #32826

Open

zannager added the scope: stepper Changes related to the stepper. label Jan 29, 2026

zannager requested a review from mj12albert January 29, 2026 16:15

ZeeshanTamboli reviewed Jan 31, 2026

View reviewed changes

ZeeshanTamboli added accessibility a11y type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Jan 31, 2026

mnajdova reviewed Feb 10, 2026

View reviewed changes

packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.ts Outdated Show resolved Hide resolved

silviuaavram force-pushed the feat/stepper-accessibility branch from d598657 to be10951 Compare February 10, 2026 13:38

silviuaavram marked this pull request as draft February 18, 2026 09:10

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Feb 19, 2026

silviuaavram force-pushed the feat/stepper-accessibility branch from 1f0ac0d to 353af74 Compare February 19, 2026 14:50

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Feb 19, 2026

silviuaavram force-pushed the feat/stepper-accessibility branch 5 times, most recently from 2c39c92 to 179c988 Compare February 26, 2026 09:50

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Feb 26, 2026

silviuaavram marked this pull request as ready for review February 26, 2026 11:54

silviuaavram force-pushed the feat/stepper-accessibility branch from c95b272 to 917952a Compare February 26, 2026 11:56

silviuaavram added 26 commits March 10, 2026 16:52

fix test condition

2785354

just let other handle tabindex

8fcd741

add upgrade entry

f715a45

move to utils and fix imports

b09fcf3

prettier

9a9ac1c

fix the imports

cb17b16

remove file

307512e

add it back

980b936

cleanup API that's not needed anymore

e5b45f5

mention aria-orientation

f7490bc

make step role presentation when it has a button

1587254

remove the api entry that is not needed anymore

6823e54

remove from translations too

c34a21c

no need for manually adding tabindex to menu items in tests

3c7581c

mention autoFocus tabinde change on list

8787dd5

accept nulls as refs

e84ce89

list components in upgrade better

b16a7ff

destructuring code review

f243cbf

stepper children check code review

0399f75

export steppercontext code review

cec3def

handleRefs exit early code review

faf15cf

bring back isTabList for Step

01c88b1

focus next wrap code review

ea3d7b1

some small improvements

d46f2fe

add keyboard navigation tests to components

fd7c138

prettier

f10f8b7

silviuaavram force-pushed the feat/stepper-accessibility branch from 29fb61a to f10f8b7 Compare March 10, 2026 14:52

silviuaavram requested a review from Copilot March 10, 2026 15:08

Copilot started reviewing on behalf of silviuaavram March 10, 2026 15:09 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

		@@ -3,5 +3,4 @@ export { default } from './Stepper';
		export { default as stepperClasses } from './stepperClasses';
		export * from './stepperClasses';



	export { default as StepperContext } from './StepperContext';

		const { focusNext, getContainerProps, getItemProps } = useRovingTabIndex({
		focusableIndex: activeItemIndex,

-  const { focusNext, getContainerProps, getItemProps } = useRovingTabIndex({
-    focusableIndex: activeItemIndex,
+  // Map the raw child index `activeItemIndex` to the corresponding focusable index
+  // used by useRovingTabIndex (which skips muiSkipListHighlight items).
+  let focusableActiveItemIndex = -1;
+  if (activeItemIndex !== -1) {
+    let currentFocusableIndex = 0;
+    React.Children.forEach(children, (child, index) => {
+      if (
+        React.isValidElement(child) &&
+        !child.props.muiSkipListHighlight &&
+        !child.type.muiSkipListHighlight
+      ) {
+        if (index === activeItemIndex && !child.props.disabled) {
+          focusableActiveItemIndex = currentFocusableIndex;
+        }
+        currentFocusableIndex += 1;
+      }
+    });
+  }
+  const { focusNext, getContainerProps, getItemProps } = useRovingTabIndex({
+    focusableIndex: focusableActiveItemIndex,

Uh oh!

Conversation

silviuaavram commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mui-bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Netlify deploy preview

Bundle size report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZeeshanTamboli left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

silviuaavram commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZeeshanTamboli commented Feb 2, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

silviuaavram commented Jan 27, 2026 •

edited

Loading

mui-bot commented Jan 27, 2026 •

edited

Loading

ZeeshanTamboli left a comment •

edited

Loading

silviuaavram commented Feb 2, 2026 •

edited

Loading