Focus visible

Configure a theme option to apply an outline keyboard focus across Material UI components.

Starting from v9.x, Material UI provides built-in support for visual keyboard focus indicator through CSS. The demos on this page opt out of the ripple to show only the focus visible indicator.

Usage

Set focusVisible: true on the theme to render a default focus indicator on every ButtonBase-derived component when it receives keyboard focus:

import { createTheme } from '@mui/material/styles';

const theme = createTheme({ focusVisible: true });

The default focus indicator is a two-pixel solid outline with palette.primary.main color, offset by two pixels:

Press Tab to move keyboard focus — the ring appears on focus.

Edit code

<ThemeProvider theme={theme}>
  <Stack spacing={2} sx={{ alignItems: 'center' }}>
    <Typography variant="body2" color="text.secondary">
      Press <kbd>Tab</kbd> to move keyboard focus — the ring appears on focus.
    </Typography>
    <Stack direction="row" spacing={2} sx={{ alignItems: 'center' }}>
      <Button variant="outlined">Outlined</Button>
      <IconButton aria-label="delete">
        <DeleteIcon />
      </IconButton>
    </Stack>
  </Stack>
</ThemeProvider>

<ThemeProvider theme={theme}>
  <Stack spacing={2} sx={{ alignItems: 'center' }}>
    <Typography variant="body2" color="text.secondary">
      Press <kbd>Tab</kbd> to move keyboard focus — the ring appears on focus.
    </Typography>
    <Stack direction="row" spacing={2} sx={{ alignItems: 'center' }}>
      <Button variant="outlined">Outlined</Button>
      <IconButton aria-label="delete">
        <DeleteIcon />
      </IconButton>
    </Stack>
  </Stack>
</ThemeProvider>

Press Enter to start editing

Inner focus indicator

Some components, for example Tab, render the focus indicator from the inside to avoid overflow-clipped container or overlapping with other elements.

Press Tab, then use the arrow keys — the ring insets so the Tabs scroller cannot clip it.

Edit code

<ThemeProvider theme={theme}>
  <Stack spacing={2} sx={{ alignItems: 'center' }}>
    <Typography variant="body2" color="text.secondary">
      Press <kbd>Tab</kbd>, then use the arrow keys — the ring insets so the Tabs
      scroller cannot clip it.
    </Typography>
    <Tabs value={0}>
      <Tab label="One" />
      <Tab label="Two" />
      <Tab label="Three" />
    </Tabs>
  </Stack>
</ThemeProvider>

<ThemeProvider theme={theme}>
  <Stack spacing={2} sx={{ alignItems: 'center' }}>
    <Typography variant="body2" color="text.secondary">
      Press <kbd>Tab</kbd>, then use the arrow keys — the ring insets so the Tabs
      scroller cannot clip it.
    </Typography>
    <Tabs value={0}>
      <Tab label="One" />
      <Tab label="Two" />
      <Tab label="Three" />
    </Tabs>
  </Stack>
</ThemeProvider>

Press Enter to start editing

To see the full list of components that show inner focus indicator, check out the full demo below.

Customization

The focusVisible can be customized by passing a CSS object to merge with the default styles.

Changing the outline color

To customize the outline, for example changing the color, pass an object with specified outline color to the focusVisible node to merge with the default outline styles:

// Recolor only; width and offset stay at the curated 2px.
createTheme({ focusVisible: { outlineColor: '#9c27b0' } });

Edit code

<ThemeProvider theme={theme}>
  <Button variant="outlined">Tab to me</Button>
</ThemeProvider>

<ThemeProvider theme={theme}>
  <Button variant="outlined">Tab to me</Button>
</ThemeProvider>

Press Enter to start editing

Use box-shadow as a second layer

A boxShadow can be additive on top of the outline. This is useful for a two-color ring (WCAG technique C40) that stays visible on any background.

To make the boxShadow flip for the inner focus indicator components, use focusVisibleVars.behavior from the styles:

import { focusVisibleVars } from '@mui/material/styles';

createTheme({
  focusVisible: {
    boxShadow: `${focusVisibleVars.behavior} 0 0 0 4px rgba(0, 0, 0, 0.4)`,
  },
});

Edit code

<ThemeProvider theme={theme}>
  <Stack
    direction="row"
    spacing={3}
    sx={{ alignItems: 'center', flexWrap: 'wrap', gap: 3 }}
  >
    {/* Outer ring: the box-shadow renders outside the Button. */}
    <Button variant="outlined">Tab to me</Button>
    {/* Inner ring: `focusVisibleVars.behavior` insets the box-shadow so the Tabs scroller cannot clip it. */}
    <Tabs value={0}>
      <Tab label="Tab one" />
      <Tab label="Tab two" />
    </Tabs>
  </Stack>
</ThemeProvider>

<ThemeProvider theme={theme}>
  <Stack
    direction="row"
    spacing={3}
    sx={{ alignItems: 'center', flexWrap: 'wrap', gap: 3 }}
  >
    {/* Outer ring: the box-shadow renders outside the Button. */}
    <Button variant="outlined">Tab to me</Button>
    {/* Inner ring: `focusVisibleVars.behavior` insets the box-shadow so the Tabs scroller cannot clip it. */}
    <Tabs value={0}>
      <Tab label="Tab one" />
      <Tab label="Tab two" />
    </Tabs>
  </Stack>
</ThemeProvider>

Press Enter to start editing

Replace outline with box-shadow

To replace the outline entirely with box-shadow indicator, set outline: 'none':

import { focusVisibleVars } from '@mui/material/styles';

createTheme({
  focusVisible: {
    outline: 'none',
    boxShadow: `${focusVisibleVars.behavior} 0 0 0 3px #1976d2`,
  },
});

Full focus visible demo

The complete set of components that render the focus indicator when focusVisible is enabled. Use the keyboard (Tab and arrow keys) to move focus and reveal the ring.

outer-ringThe ring renders fully outside the component.

Button

IconButton

ButtonGroup

ToggleButton

Fab

Chip

Clickable

Deletable

Checkbox

Checkbox ACheckbox B

Radio

Radio ARadio B

Switch

Pagination

ButtonBase

AccordionSummary

Details

TableSortLabel

Name	Size
file.txt	12 KB

Slider

Link

Text link

Breadcrumbs

Rating

inner-ringInside a scrollable or overflow-clipped container — the ring is inset (outlineOffset -2) so it cannot be clipped.

Tab

Stepper

MenuItem

ListItemButton

List item

BottomNavigation

CardActionArea

Select

Autocomplete

Focus visible

Usage

Inner focus indicator

Customization

Changing the outline color

Use box-shadow as a second layer

Replace outline with box-shadow

Full focus visible demo

Accordion header