Skip to content

Unstable_TrapFocus API

API documentation for the React Unstable_TrapFocus component. Learn about the available props, and the CSS API.

Import

import Unstable_TrapFocus from '@material-ui/unstyled/Unstable_TrapFocus';
// or
import { Unstable_TrapFocus } from '@material-ui/unstyled';
You can learn about the difference by reading this guide on minimizing bundle size.

Utility component that locks focus inside the component.

Props

NameTypeDefaultDescription
open*boolfalseIf true, focus is locked.
childrenelementA single child content element.
⚠️ Needs to be able to hold a ref.
disableAutoFocusboolfalseIf true, the trap focus will not automatically shift focus to itself when it opens, and replace it to the last focused element when it closes. This also works correctly with any trap focus children that have the disableAutoFocus prop.
Generally this should never be set to true as it makes the trap focus less accessible to assistive technologies, like screen readers.
disableEnforceFocusboolfalseIf true, the trap focus will not prevent focus from leaving the trap focus while open.
Generally this should never be set to true as it makes the trap focus less accessible to assistive technologies, like screen readers.
disableRestoreFocusboolfalseIf true, the trap focus will not restore focus to previously focused element once trap focus is hidden.
getDocfuncfunction defaultGetDoc() { return document; }Return the document the trap focus is mounted into. Provide the prop if you need the restore focus to work between different documents.
getTabbablefuncReturns an array of ordered tabbable nodes (i.e. in tab order) within the root. For instance, you can provide the "tabbable" npm dependency.

Signature:
function(root: HTMLElement) => void
isEnabledfuncfunction defaultIsEnabled() { return true; }This prop extends the open prop. It allows to toggle the open state without having to wait for a rerender when changing the open prop. This prop should be memoized. It can be used to support multiple trap focus mounted at the same time.

The component cannot hold a ref.

Demos