[material-ui] Add theme.focusVisible opt-in keyboard focus ring

[siriwatknp]

Docs: https://deploy-preview-48743--material-ui.netlify.app/material-ui/customization/focus-visible/

Summary

Implements the opt-in, themeable keyboard focus ring from RFC #48718.

A single theme key, theme.focusVisible, styles the Mui-focusVisible state — the keyboard-focus state ButtonBase already tracks — across ButtonBase and every component that builds on it, with no per-app wiring. It's aimed at teams that turn off the Material Design ripple (disableRipple) and are otherwise left with no visible keyboard-focus indicator (a WCAG 2.4.7 gap).

createTheme({ focusVisible: true });
// or customize — merges over the curated default:
createTheme({ focusVisible: { outlineColor: '#9c27b0', outlineOffset: 3 } });

Value	Behavior
undefined	No ring — default, fully non-breaking (zero visual diff)
true	Curated ring: 2px solid, primary.main, 2px offset
object (FocusVisible = React.CSSProperties)	Merged over the curated default
false	Reserved kill-switch for the deferred auto-on fallback

Rendered with CSS outline (survives Windows High Contrast / forced-colors, no layout shift, no collision with the box-shadow elevation Button/Fab already animate). Coverage:

• Free via ButtonBase — Button, IconButton, Fab, and any custom ButtonBase consumer.
• Clip-prone families inset the ring so a scroller/overflow ancestor can't cut it — Tab, MenuItem, ListItemButton, CardActionArea, BottomNavigationAction, and the Autocomplete option (a plain <li>).
• Slot-drawn controls put the ring where it reads, not on the padded hit area — Checkbox/Radio (icon svg), Switch (track), Slider (thumb), Rating (active icon + empty-value label), Link (component="button").

Ships with an exported FocusVisible type and a guide at customization/focus-visible.

For Reviewers

Hide whitespace when review.

Color resolution lives in three places, one per theme mode. The geometry (outlineWidth/Offset/Style + inset-var wiring) is shared by resolveFocusVisible in styles/focusVisible.ts; only the default outlineColor differs:

1. createTheme({ focusVisible: true })
   • Resolved in: createThemeNoVars.js
   • Default outlineColor: resolved hex off palette.primary.main
   • Dark mode: — (single scheme)
2. createTheme({ focusVisible: true, colorSchemes: { light, dark } })
   • Resolved in: createThemeNoVars.js (default scheme, top-level) + createTheme.ts (per-scheme copy)
   • Default outlineColor: each scheme's own primary.main
   • Dark mode: swaps on useColorScheme mode change
3. createTheme({ cssVariables: true, focusVisible: true })
   • Resolved in: createThemeWithVars.js
   • Default outlineColor: var(--mui-palette-primary-main)
   • Dark mode: adapts at the CSS level

Scenario 2 needs extra care: without CSS vars the provider switches schemes by shallow-merging colorSchemes[mode] onto the theme and re-rendering (no CSS var to adapt). So createTheme.ts gives each scheme its own resolved focusVisible, and that same merge swaps the outline color per mode — exactly as it does palette. Scenario 3 needs no per-scheme copy because the palette var adapts on its own.

Inset contract (private CSS vars). Clip-prone roots spread applyInsetFocusVisible, which sets --_focusVisible-offset (flips the outline-offset sign, outset→inset) and --_focusVisible-behavior (makes a user boxShadow inset). wireFocusVisibleVars bakes the resolved offset/box-shadow to read those vars, so a component never has to know the ring width — the same customized ring insets or not per component with no field mapping.

Multi-layer box-shadow is not supported. The behavior var is prepended once, in front of the whole value. A comma-separated boxShadow is a list of independent layers, so only the first one insets on clip-prone components. The rest stay outset and get clipped.

Supporting it would need a depth-aware parser in createTheme. Splitting on comma is not safe, because commas also appear in var() fallbacks and rgb() colors. Even with a parser it stays incomplete, since var(--my-ring) can expand to several layers at computed time.

I think this case is rare. Not worth a partial CSS parser in the theme factory. Outline + a single box-shadow already covers the WCAG C40 two-color ring, and styleOverrides handles a multi-layer ring on one component. Called out in the customization guide.

CSS variables. focusVisible is skipped from var generation (shouldSkipGeneratingVar) and kept inline: hoisting it to :root would resolve the per-component private vars where they're unset, breaking the inset. Inline + palette var keeps both the inset and the scheme-reactive color working.

ButtonBase gate. The root ring is gated by a private internalDisabledThemeFocusVisible prop (default false); the whole variant is a no-op when theme.focusVisible is unset. SwitchBase sets it true so Checkbox/Radio/Switch suppress the root ring and draw on their slot instead.

styles/focusVisible.ts. One module holding the shared resolver and the inset contract. Named exports: resolveFocusVisible / extractFocusVisibleInput (feed the three resolution sites), wireFocusVisibleVars, outsetFocusRing, applyInsetFocusVisible, and applyChildrenFocusVisible (colored surfaces set the ring's shadow slot through it) — the private var names stay module-internal.

Tests. createTheme.test.js (normalization + per-scheme + vars) and createTheme.spec.ts (types); computed-style tests across ButtonBase, Tab, Checkbox, Radio, Switch, Slider, Rating, Link, Autocomplete, Fab, Button; ThemeProvider.test.tsx drives setMode('dark') and asserts the outline color follows the active scheme. Visual-regression fixtures under test/regressions/fixtures/FocusVisible/ cover the ring across the inset families, selection controls, the Autocomplete option, and forced-colors mode. The fixtures render already focus-visible (they force the Mui-focusVisible class on mount — faithful, since the ring is class-driven, not :focus-visible-driven), so the standard screenshot loop captures each in one shot with no redundant un-focused baseline.

Colored surfaces (in scope). Saturated containers (color-variant AppBar, filled Alert, SnackbarContent) set a private --_focusVisible-shadow var (0 0 0 4px background.default); the curated ring's box-shadow slot (var(--_focusVisible-shadow, 0 0)) consumes it, drawing a background-colored halo behind the outline so the indicator keeps contrast there. A custom boxShadow in theme.focusVisible replaces that slot — surface contrast is then the author's call.

RFC: #48718

[code-infra-dashboard]

Deploy preview

• docs/data/material/customization/focus-visible/FocusVisibleBoxShadow.js

  
  
• docs/data/material/pages.ts

  
  

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+5.31KB(+1.00%)	🔺+1.15KB(+0.75%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/private-theming	0B(0.00%)	0B(0.00%)
@mui/system	0B(0.00%)	0B(0.00%)
@mui/utils	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[silviuaavram]

One last comment related to the controlled components. The rest looks good to me, great effort here!

[LukasTy]

Looks awesome! 💯
Great work, thanks for the massive continued effort on this! 👍

A few non-blocking nitpicks:

1. Have you considered a bigger offset on the Switch outline or having a separate demo rebuilding a switch from a different design system?
   The current variant feels a bit too "crammed", where the outline is glued together with the thumb.

2. Opening Autocomplete does not apply the focus outline to the selected item.
   Is it a result of the Autocomplete component behavior or a slight bug?

---

Some additional AI Nitpicks

Claude

Autocomplete.js:398 is the only ungated focus tint left. I scanned every component that carries a .Mui-focusVisible background rule. Chip (5 rules), PaginationItem (4), AccordionSummary, MenuItem (2), ListItemButton (2), and CardActionArea are all gated. The [aria-selected="true"] combined rule in Autocomplete is not.

Measured on a listbox option with the ring enabled:

• unselected: bg=rgba(0, 0, 0, 0) -- tint suppressed, ring solid 2px
• selected: bg=rgba(25, 118, 210, 0.2) -- the selected-plus-focus tint still applies, ring solid 2px

So when a user moves through the list with the arrow keys, the highlight jumps in intensity on the selected option. MenuItem gates the equivalent rule at line 88. The fix is one guard. The effect is cosmetic, not an accessibility problem.

One note for the record. The isResolvedFocusVisible heuristic carries a documented edge in its own comment: a theme that pins outlineColor to exactly the light primary.main and is then recomposed loses that pin and re-derives per scheme. The trade-off is reasonable and the comment states it.

Codex

One final pass found four material issues:

1. Selected Autocomplete options still retain the legacy focus tint. With theme.focusVisible, keyboard focus changes the selected background from 0.12 to 0.20, contradicting the docs that the theme ring replaces built-in focus-visible styles. Gate the selected .focusVisible rule behind !theme.focusVisible.

2. Wider outlines are not fully inset. With { outlineWidth: 4 }, MenuItem computes outlineOffset: -2px, leaving half the outline outside the clipped container. If the fixed offset remains intentional, document that widths above 2 require a matching outlineOffset; otherwise ensure the inset magnitude is at least the width.

3. The full demo still places Stepper in the inner-ring bucket, which promises outlineOffset: -2px. StepButton now outlines StepLabel with the normal outset +2px geometry, matching the final RFC. Move it to the outer-ring bucket.

4. The linked prototype contains stale guidance:

   • Its JSON placeholder exposes the private --_focusVisible-behavior variable instead of accepting a plain boxShadow.
   • It says contained Button may override a custom focus shadow, but Button now composes it like Fab.
   • It describes a disabled.focusVisible outline that does not exist; ButtonBase clears focus-visible when disabled.

The RFC precedence wording should also say the curated default has “no visible box-shadow on ordinary surfaces,” since it always carries the private colored-surface shadow slot.