[RFC] theme.focusVisible — opt-in keyboard focus ring

[siriwatknp]

Prototype: #48743

What's the problem?

Material UI's focus indicator is the ripple (Material Design).

Some teams opt out of Material Design. Flat look, no ripple. After that, no keyboard-focus indicator is left.

So they build a focus ring by hand, on every interactive component. There is no built-in, themeable focus ring today.

By hand is painful in two ways:

• No single switch. Must wire it on Button, IconButton, Tab, MenuItem, and every other interactive component.
• Per-component geometry. An outset outline is clipped on components inside overflow: hidden (Tab, MenuItem…). Each one needs an inset ring with a flipped outlineOffset.

This RFC proposes a built-in, opt-in theme.focusVisible. One theme key turns the ring on everywhere. Material UI handles outlineOffset for components where the ring would clip, so the consumer does not tune geometry.

It also prepares for auto-restoring the indicator when the ripple is off (WCAG 2.4.7). That automatic part is a separate follow-up.

What are the requirements?

1. One theme key renders the ring across ButtonBase and every derived component. Zero per-component code for the consumer.
2. A curated default that is safe to turn on anywhere. No collision with existing focus styles.
3. Customization is additive. A provided object merges over the safe outline default. So adding a box-shadow gives a two-color focus indicator (WCAG C40), and removing the outline is explicit.
4. Non-breaking. An unconfigured theme renders the same as today.
5. Works without extra setup across components, including ones where an outset ring would clip.
6. Survives forced-colors. No layout shift. Color stays scheme-reactive under CSS theme variables.

What are our options?

Ring technique. outline is the default. It survives forced-colors. It does not collide with the box-shadow elevation that Button and Fab animate on focus. It follows border-radius. box-shadow is additive on top, but on its own it is stripped in forced-colors and can collide with elevation. ::after is rejected.

API shape. Full React.CSSProperties over an outline-only subset, so any technique works. Partial override over verbatim. A provided object merges over the curated default, so the safe outline stays unless the consumer removes it. This supports a two-color indicator (outline plus box-shadow, WCAG C40), and avoids the case where a partial outline renders nothing. A true flag for the curated default.

Placement. A single rule on ButtonBase, over per-component rules or GlobalStyles.

Proposed solution

theme.focusVisible: boolean | React.CSSProperties, applied on Mui-focusVisible:

Value	Behavior
undefined	No ring (default)
true	Curated outline default, safe against existing styles
object	Merged over the curated default (partial override)
false	Reserved kill-switch (see Reserved false)

createTheme({ focusVisible: true });                                    // curated outline ring
createTheme({ focusVisible: { boxShadow: '0 0 0 4px #fff' } });         // outline + box-shadow (two-color, WCAG C40)
createTheme({ focusVisible: { boxShadow: '0 0 0 4px #fff', outlineColor: 'transparent' } }); // box-shadow only

Curated default: { outlineStyle: 'solid', outlineColor: palette.primary.main, outlineWidth: 2, outlineOffset: 2 }. The outlineOffset is a fixed 2 — it does not scale with a custom outlineWidth; a custom outlineOffset replaces it.

A provided object merges over this default. So { outlineColor: '#f00' } keeps the solid 2px ring and only changes the color. To drop the outline part, set outlineColor: 'transparent' (invisible, keeps geometry) or outlineWidth: 0 (full removal). This follows WCAG C40, where an outline and a box-shadow combine into one indicator. See the two-color focus example.

Implementation, zero per-component code for the consumer. The value is resolved to the curated object at createTheme time (true is the default; an object merges over it). One theme.focusVisible rule on ButtonBase reaches all derived components, since they are styled(ButtonBase). The default color points at the primary.main palette variable, so it stays scheme-reactive under CSS theme variables (correct in dark mode).

Inner ring components

if the ring is outer:

Some components render inside a clipping container — a Tabs scroller, a scrolling menu or list, a Card's overflow: hidden. An outset ring is clipped there, so Material UI insets the ring automatically on those components. One theme key looks right everywhere, with no geometry tuning by the consumer:

createTheme({ focusVisible: true });
// outset by default; inset on Tab, MenuItem, ListItemButton, CardActionArea,
// and BottomNavigationAction — where an outset ring would clip.

Each inner-ring component sets a private CSS variable on its root that the shared ring reads and flips the outline inward:

Customization rides the same var, wired internally: createTheme prepends it to a custom boxShadow and wraps a custom outlineOffset, so a customized ring insets here too. The consumer writes plain CSS and never references a var (the var handles are not public API).

A custom outlineOffset is a positive magnitude; the inset direction is managed by the sign var, so a negative offset is unsupported (it would flip to outset on clip-prone components). For a literal signed offset, override the specific component's .Mui-focusVisible via styleOverrides. The sign var is a multiplier: most inset families mirror the offset 1:1, but Tab insets deeper (3×, −6px with the curated 2px offset) so the ring does not overlap the selected-tab underline indicator.

Multi-layer box-shadow rings (comma-separated, e.g. a double C40) are out of scope for the automatic inset — only the first layer insets on clip-prone components; use styleOverrides for a multi-layer ring inside a clip-prone component.

Precedence. An explicit theme.focusVisible box-shadow wins over a component's own focus box-shadow (contained Button/Fab elevation, Slider's color halo) — each re-asserts theme.focusVisible after its own shadow in the same rule. The curated outline-only default has no box-shadow, so those elevations/halos stay intact.

Scope

Scope is defined by mechanism: every component that renders ButtonBase, plus the .Mui-focusVisible carriers wired explicitly.

• Automatic via the ButtonBase rule: Button, IconButton, Fab, ToggleButton, and bare ButtonBase.
• Inner ring (inset, clip-prone): Tab, MenuItem, ListItemButton, BottomNavigationAction, CardActionArea.
• SwitchBase controls — ring on a slot, not the ButtonBase root: Checkbox and Radio outline the icon svg; Switch outlines the track (see Switch). The root ring would land on the padded hit area (or the thumb), which is uncommon for these, so they opt the root out and draw the ring on the relevant slot instead — no double ring.
• ButtonBase when interactive: Chip (clickable or deletable).
• Non-ButtonBase, wired explicitly because they own .Mui-focusVisible: Slider (thumb), Link, Autocomplete (listbox option — inset, the listbox scrolls), and Rating (active icon + empty-value label).
• Out of scope: inputs that do not carry .Mui-focusVisible through these paths — TextField / InputBase and friends keep their own indicators.

In scope — ring contrast on colored surfaces. The curated ring is primary.main, tuned for standard paper/background surfaces. On a saturated container — an AppBar with a palette color, a filled Alert, an inverted SnackbarContent — a primary outline alone can lack contrast. Those containers therefore set a private --_focusVisible-shadow var (0 0 0 4px background.default) that the curated ring's box-shadow slot (var(--_focusVisible-shadow, 0 0)) consumes: a background-colored halo renders behind the outline, keeping the indicator visible on the saturated surface. A custom boxShadow in theme.focusVisible replaces that slot (normal merge semantics), so ring contrast on those surfaces becomes the author's responsibility — e.g. a contrasting outlineColor scoped to the surface. The prototype's "on a colored surface" section shows the case.

Reserved false and the auto-on follow-up

Today undefined and false both render no ring. They diverge when the deferred auto-on fallback lands: at that point undefined will mean "ring whenever disableRipple removes the only indicator", which is a visual change for apps that already hand-rolled a ring (they would get a double ring). false is the escape those apps set now to stay opted out through that transition. Reserving it in v1 keeps the follow-up non-breaking.

Prototype

Implemented in #48743. Live prototype — every ButtonBase-derived component, with a preset switcher (curated / recolor / two-color C40 / box-shadow-only), light/dark, and a CSS-variables toggle:

https://deploy-preview-48743--material-ui.netlify.app/experiments/focus-ring/

Decision need

✅ Naming — resolved: focusVisible

Naming of the field. Candidates were focusRing, focusIndicator, focusVisible. Decision: focusVisible.

The key styles the .Mui-focusVisible state, wherever that state appears — not only a ButtonBase artifact. The prototype proves this: it wires the same value into Slider's thumb and Link, which are not ButtonBase but carry .Mui-focusVisible. Naming the key after the state it targets (focusVisible) is therefore more accurate than an artifact name (focusRing), maps 1:1 to the .Mui-focusVisible class a developer sees in devtools, and reuses Material UI's own established vocabulary (.Mui-focusVisible, focusVisibleClassName) instead of importing a term from other libraries. It also reads as keyboard-only (:focus-visible), which focusIndicator would blur against :focus. "Focus ring" stays as the informal feature name in prose/docs; the API key is focusVisible.

✅ Switch

Which appearance should be? Option 2 (on the track slot)

1. With default focus on ButtonBase, the outline shown on the thumb which is not common:

2. show outline on the track slot (need to adjust force opacity to 1 because prior styles uses opacity to dim the background color).

when customized, it looks like this:

✅ Radio & Checkbox (option 2, on svg)

1. the default focus visible on ButtonBase

2. targeting on svg:

Resources and benchmarks

• Experiment PR: [ButtonBase] Add theme.focusRing for keyboard focus ring #48647 (preview and demo)
• WCAG 2.4.7 Focus Visible
• WCAG C40: Creating a two-color focus indicator — https://www.w3.org/WAI/WCAG22/Techniques/css/C40 (working example: https://www.w3.org/WAI/WCAG22/working-examples/css-two-focus-colors/)
• Follow-up (deferred): automatic a11y fallback when the ripple is disabled

[mj12albert]

The overall direction seems good, some thoughts:

1. Not sure that "focus ring" is the best name for API, it sounds a bit too casual, but I don't have any great suggestions at the moment ("focus indicator"? "focus outline"?)
2. Roll out: what do you think about starting with a PR for Button + IconButton (matching [button] Enable buttons to remain focusable when disabled #48613), and then open per-component PRs that opt into both features focusableWhenDisabled and theme.focusRing together? @siriwatknp

[siriwatknp]

Not sure that "focus ring" is the best name for API, it sounds a bit too casual

"focus indicator" sounds best to me. I'll wait for final thought from @LukasTy

Roll out: what do you think about starting with a PR for Button + IconButton

Sounds good, I can do that. That's going to be hard, my approach is to apply to ButtonBase. Let me see how can it be breaking down to individual components.

[mj12albert]

my approach is to apply to ButtonBase

Thats ok too if you think it's easier ~

non-ButtonBase inputs like TextField and Checkbox

Checkbox also uses ButtonBase via SwitchBase though, same for Radio and Switch, so there would still need to be a way to exclude components if you intend to keep these out of scope?

[siriwatknp]

Instead of "focus indicator", I think it's more explicit to use "focus visible" so anyone knows that it applies for keyboard navigation.

"focus indicator" could confuse user for :focus and :focus-visible.

cc @LukasTy

[LukasTy]

Verdict: the direction is sound -- opt-in theme key, outline as the baseline, one rule on ButtonBase, merge-over-curated-default -- and the prototype (#48743) validates the hard parts (forced-colors, no elevation collision, scheme-reactive vars). Applying at ButtonBase in a single PR is also the right rollout; per-component splitting would duplicate the rule and still miss bare ButtonBase usage. The gaps are in the RFC text and semantics, not the architecture:

• The scope statement is wrong. Checkbox/Radio/Switch render ButtonBase via SwitchBase, so the rule covers them (the prototype even ships a Switch overflow: visible fix), and clickable Chip renders ButtonBase too. Define scope by mechanism ("everything that renders ButtonBase") with a component list, plus the exclusion recipe (styleOverrides with outlineColor: 'transparent' -- not outline: 0, which kills the forced-colors fallback). The principled framing: the ButtonBase family is exactly the set whose only keyboard indicator is the ripple; Slider, Link, and TextField keep their own indicators.
• outlineOffset semantics: RFC and prototype disagree. The RFC says a user-provided offset "overrides them everywhere"; the prototype always insets Tab/MenuItem/etc. because after normalization it can't tell user-set 2 from the curated 2. Recommend dropping the promise (insets win, styleOverrides is the escape hatch) and aligning the RFC text. Same for the --mui-focusRing-outlineOffset var override, which won't reach inset components.
• The inset list needs a systematic audit. TabScrollButton (ButtonBase, inside Tabs' overflow: hidden root) is already missed. Sweep all ButtonBase consumers inside MUI-owned clipping containers, add visual regression coverage, and document that consumer-owned overflow: hidden needs the inset recipe on their side.
• Pin the auto-on follow-up interplay now. When the a11y fallback lands, undefined changes meaning from "no ring" to "ring whenever disableRipple" -- a visual change for apps with hand-rolled rings (double ring). That is the real justification for reserving false, and the RFC should spell it out.
• Naming: focusRing over focusVisible. focusVisible names the state, not the artifact, and overpromises -- Slider's thumb and Link carry .Mui-focusVisible but are untouched by this feature. And focusVisible: false reads like "disable focus-visible detection", which is exactly wrong for the reserved kill-switch. "Ring" is the established term (React Aria useFocusRing, Chakra focusRing, Tailwind ring utilities), and the prototype already exports FocusRing and --mui-focusRing-*.
• Prototype housekeeping: docs/adr/0002 still documents the old auto-on model as "accepted", contradicting the v1 opt-in scope; and createThemeWithVars normalizes from options.focusRing only, so createTheme({ cssVariables: true }, { focusRing: true }) leaves a raw boolean in the vars path.

[siriwatknp]

Thanks for the review. Very helpful.

Checked each point against the prototype. Most land. Two I am not fully sure about, pushing back below. Updated the RFC. Pushed fixes in e4a2d5e.

1. Scope statement. Fixed. Scope by mechanism now: everything that renders ButtonBase, with the list. Added Checkbox/Radio/Switch via SwitchBase, and clickable/deletable Chip. Exclusion recipe too: styleOverrides with outlineColor: 'transparent', not outline: 0, to keep the forced-colors fallback. One thing on the framing. It is not only the ripple-only set. The prototype also wires Slider thumb and Link. They are not ButtonBase but carry Mui-focusVisible. Related to naming below.

2. outlineOffset. Agreed, the RFC over-promised. Dropped "overrides everywhere". Inset wins on the clip-prone components, they recompute from outlineWidth. A user offset reaches the non-clipped ones only. styleOverrides is the escape hatch. Text matches the prototype now.

3. TabScrollButton. Ran the sweep. But not sure about TabScrollButton. It renders role={null} and tabIndex={null}, so it is not keyboard-focusable. Mui-focusVisible never lands, no ring to clip. So I left it not inset. Does that match what you saw? Rest of the sweep is clean. ToggleButtonGroup has border-radius but no overflow: hidden. Chip overflow: hidden is on the label span, not the root. Documented that a consumer-owned overflow: hidden needs the recipe on their side.

4. Auto-on. Pinned it in the RFC and adr/0002. undefined changes meaning when the fallback lands: ring whenever disableRipple. Double-ring risk for apps that rolled their own. That is why false is reserved now.

5. Naming. I lean to keep focusVisible. Two things. Small correction first: no FocusRing export or --mui-focusRing-* var today. The API is focusVisible throughout. "focus ring" is just the informal name in the docs and ADR paths. Second, the main reason: the key styles the Mui-focusVisible state wherever it is, not a ButtonBase ring. The prototype wires Slider thumb and Link for that reason. So the state name maps 1:1 to what you see in devtools, and reuses our own words, Mui-focusVisible and focusVisibleClassName. On false reading like "disable detection", fair. So I documented the reserved semantics instead of the name carrying it. Open to more thoughts though.

6. Housekeeping. adr/0002 rewritten: v1 opt-in only, auto-on deferred. Vars-path fixed: createTheme({ cssVariables: true }, { focusVisible: true }) normalizes now instead of a raw boolean, with a test. Both in e4a2d5e.

[LukasTy]

Checked e4a2d5e against each point -- nice turnaround, most of it lands cleanly. One concession from my side, then the remaining follow-ups.

TabScrollButton: you're right, I missed it. It renders component="div" with role={null}/tabIndex={null}, so it's never keyboard-focusable and .Mui-focusVisible can't land on it. Leaving it un-inset is correct, and the sweep note in the RFC covers it well.

Naming: conceding focusVisible. Wiring Slider and Link makes the state-based rationale coherent, and reusing the existing Mui-focusVisible / focusVisibleClassName vocabulary is a fair argument. One condition though: that rationale only holds if the carrier set is actually complete, which leads to the main remaining gap.

1. Rating is a third .Mui-focusVisible carrier, and it's neither wired nor listed. It applies the class to its root and indicates focus with a hardcoded outline: '1px solid #999' on the active icon (Rating.js:90) -- non-themeable and low-contrast in dark mode, so it's arguably the component that needs this feature most. Note the class lands on the root while the meaningful indicator belongs on the active star, so a naive object spread would ring the whole row; it needs per-component curation the same way Autocomplete got its inset, e.g. '&.Mui-focusVisible .MuiRating-iconActive' receiving the ring object. Either wire it or list it in the scope section with a reason -- as-is it contradicts both the scope statement and the naming rationale.
2. The scope list already lags the prototype again. The RFC says two explicit carriers (Slider thumb, Link), but the PR wires three: the Autocomplete listbox option is also covered (good addition -- the option only carries the class via keyboard highlight, and the inset is right for the scrolling listbox). Update the list.
3. Enforce the carrier invariant with a test. "Styles the state wherever it appears" is now a contract: every current and future Mui-focusVisible emitter must receive the value or the API lies. Rating shows a manual sweep misses carriers (the e4a2d5e audit swept clipping containers, which is a different axis). A conformance-style test that iterates the known emitters and asserts the ring's computed style would keep future components honest.
4. One line for the RFC on box-shadow precedence. With a user-provided boxShadow, Slider's thumb halo loses to the user shadow on focus-visible (source order), while contained Button/Fab elevation wins over it. Opposite outcomes for the same input -- both defensible, but state it so it reads as intended rather than accidental.

[siriwatknp]

Thanks again for digging in.

Checked each point.
Here is where things stand.

1. Rating.
   Fixed.
   Wired theme.focusVisible onto the active icon only, &.Mui-focusVisible .MuiRating-iconActive.
   Kept the old outline: 1px solid #999 as fallback when the theme key is unset.
   So an unconfigured theme still renders the same as before.
   Added a row to the demo page.
   Added two tests, curated ring case and legacy fallback case.
   Pushed to focus-ring-v1 ([material-ui] Add theme.focusVisible opt-in keyboard focus ring #48743).

2. Scope list.
   Updated.
   Non-ButtonBase carrier list was undercounting.
   Now lists Slider, Link, Autocomplete (listbox option), Rating (active icon).
   Note on Rating: the class lands on the root, the whole star row is one focus group, but the ring targets the icon child only.
   Same kind of per-component curation as the Autocomplete inset, not a plain root spread.

3. boxShadow precedence.
   Looked into this properly instead of taking the "opposite outcomes" framing at face value.
   Checked compiled CSS rule order for Button and Slider, not computed style.
   Computed style was misleading me at first, caught it mid transition.
   Finding: in both cases the component's own box-shadow rule wins, not the user's.
   Not opposite.
   Each component's own .Mui-focusVisible box-shadow is declared after the ButtonBase-injected theme.focusVisible rule in source order.
   Same specificity, later rule wins the cascade.
   One mechanism, not a per-component split.
   To replace a built-in focus shadow, styleOverrides on the component itself is the escape hatch.
   Flagging this plainly since it corrects the original guess, not confirms it.

One note on process.
Normally 2 and 3 go straight into the RFC text, like last round.
Could not edit the issue body this time.
Writing the intended text changes here instead, will fold into the body once I can.

4. Conformance test.
   Not doing this yet.
   Proposing it as the next step once the RFC itself is approved.
   Test should lock in an agreed contract, not a moving target.

[LukasTy]

Thanks for the replies.
I've checked the latest demo and have a few follow-ups notes.

Rating

I feel like the 0 rating outline should also match the same blue outline style.
Currently, it's the same thin gray outline as on master.
WDYT?

More explicit handling

The focus outline on some components feels a bit too "far" from the control.
WDYT about handling some cases more explicitly?

• Checkbox, Radio and Stepper -> outline on nested SVG
• Switch -> outline on nested thumb