mui/material-ui · error · Error

MUI: RovingTabIndexContext is missing. Roving tab index item

Error message

MUI: RovingTabIndexContext is missing. Roving tab index items must be placed within a roving tab index provider.

What it means

RovingTabIndexContext (in @mui/utils useRovingTabIndex) is provided by a roving-tab-index root (e.g. Menu/MenuList in MUI) and consumed by items that participate in arrow-key navigation. useRovingTabIndexContext throws when the value is undefined, meaning the calling item is not inside a roving-tab-index provider. The pattern (roving tabindex) requires a coordinator root to track which item is tabbable.

Source

Thrown at packages/mui-utils/src/useRovingTabIndex/RovingTabIndexContext.tsx:19

'use client';
import * as React from 'react';
import type { UseRovingTabIndexReturnValue } from './useRovingTabIndex';

type RovingTabIndexContextValue = UseRovingTabIndexReturnValue<unknown>;

export const RovingTabIndexContext = React.createContext<RovingTabIndexContextValue | undefined>(
  undefined,
);

if (process.env.NODE_ENV !== 'production') {
  RovingTabIndexContext.displayName = 'RovingTabIndexContext';
}

export function useRovingTabIndexContext() {
  const context = React.useContext(RovingTabIndexContext);

  if (context === undefined) {
    throw new Error(
      'MUI: RovingTabIndexContext is missing. Roving tab index items must be placed within a roving tab index provider.',
    );
  }

  return context;
}

View on GitHub (pinned to bdc96df2cb)

Solutions

Render the item within a subtree that provides RovingTabIndexContext (typically by using the MUI Menu/MenuList or a component that wires useRovingTabIndex at its root).
If building a custom composite widget, call useRovingTabIndex at the root and wrap children in RovingTabIndexContext.Provider.
Avoid portalling focusable items out of the rooted composite.

Example fix

// before — item rendered without a roving-tabindex root
<CustomItem />
// after — wrap in a root that provides the context (e.g. MenuList)
<MenuList>
  <CustomItem />
</MenuList>

Defensive patterns

Strategy: validation

Validate before calling

// Structural guard: ensure the consuming item is rendered inside a component that provides RovingTabIndexContext.
// In user code this means: only use roving-tabindex items within <Menu>/<MenuList>/<Select> or a custom root that calls useRovingTabIndex and wraps children in <RovingTabIndexContext.Provider>.

Prevention

Render roving-tabindex items only inside a rooted composite (Menu, MenuList, or a custom provider).
When building a custom composite, set up useRovingTabIndex at the root and provide RovingTabIndexContext to descendants.
Do not portal focusable items out of the rooted subtree.

When it happens

Trigger: Rendering a component that calls useRovingTabIndex/useRovingTabIndexContext outside of a roving tab index root (e.g. a ListItem or custom focusable item without the provider); portalling such an item out of the rooted subtree.

Common situations: Building a custom toolbar/menu with roving-tabindex items but forgetting the root hook/provider; refactoring that detaches an item from the rooted list.

Related errors

AI-assisted analysis of mui/material-ui@bdc96df2cb (2026-08-12). Data as JSON: /api/errors/5f8cef702b7d0b20. Report an issue: GitHub.