FocusTrap

Install: npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1

Version and compatibility

Pinned Mantine Core 9.7.1 requires React and React DOM ^19.2.0 and matching @mantine/hooks@9.7.1, from the installed npm package's peerDependencies. Do not force it into React 18 or another incompatible version. Explain upgrade impact and agree on a plan with the project owner; do not hide conflicts with --force/--legacy-peer-deps. The native Provider enables theme.respectReducedMotion and uses forceColorScheme for light/dark.

Use case

Keep keyboard focus inside an active region.

Native props used by this example

These props are extracted from the local typechecked JSX and grouped by their owning native component. This is not an exhaustive prop list; see pinned source signatures and inheritance below.

Interaction and state checks

Current scenarios: Default. Check actual behavior after selecting supported disabled/error/read-only scenarios; components without those native states do not receive invented universal props. Verify keyboard focus and exits, then connect changed values through the native callback signature.

Business integration boundary

Enable only for a genuine focused workflow, provide an exit and restore the triggering focus. A visual panel alone is not a modal dialog.

Host setup

Install pinned @mantine/core and @mantine/hooks, import @mantine/core/styles.css at the entry and use MantineProvider. The example's theme/variant are JGuang-authored host props, not universal native component APIs; forceColorScheme synchronizes the app theme. Native implementation source is a reading reference: use npm exports rather than copying internal engines. This batch covers Core, not dates/charts/forms extension packages. Detailed upstream prose remains English.

Runnable usage

import { useState } from 'react';
import * as M from '@mantine/core';
import '@mantine/core/styles.css';


function ComponentPreview({ variant = 'Default' }: { variant?: string }) {
const [open, setOpen] = useState(false);
return <M.FocusTrap active={open}><div onKeyDown={(event) => { if (event.key === "Escape") setOpen(false); }}><M.Button onClick={() => setOpen(!open)}>Focus trap {open ? "on / 开启" : "off / 关闭"}</M.Button><M.TextInput aria-label="Focus trap input / 焦点锁定输入" placeholder="Tab through controls" /></div></M.FocusTrap>;
}
export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) {
return <M.MantineProvider forceColorScheme={theme} theme={{ respectReducedMotion: true }}><ComponentPreview variant={variant} /></M.MantineProvider>;
}

Preview states

Default

The example uses the native Mantine API. For supported input demos, change the local variant to Disabled, Invalid or Read only; these are example labels, not new component props. Keep the documented data, controlled values, stores and compound children when adapting the example.

Usage

FocusTrap is a component implementation of the use-focus-trap hook. It is used in all Mantine components that require focus trap (Modal, DatePicker, Popover, etc.).

Initial focus

To define the element that will receive initial focus, set the data-autofocus attribute:

FocusTrap.InitialFocus

FocusTrap.InitialFocus is a special component that adds a visually hidden element which will receive the focus when the focus trap is activated. Once FocusTrap.InitialFocus loses focus, it is removed from the tab order.

For example, it is useful if you do not want to focus any elements inside the Modal when it is opened:

Focus trapping logic

• Focus is trapped within the child node if the active prop is true
• When the FocusTrap component is mounted or when the active prop changes from false to true, the first element with the data-autofocus attribute is focused
• If there are no elements with the data-autofocus attribute, then the first element that supports keyboard interaction is focused
• If the target element does not have focusable elements or does not support ref, then the focus trap will not work
• Trap stops working when an element outside of the FocusTrap child is focused

Source-backed parameter reference

Implementation signatures and types are generated from the pinned local source. Optional props, native inherited types, union branches and never exclusions are preserved. A forwardRef implementation's ref is a React reference, not an additional business prop.

FocusTrap({
  children,
  active = true,
  refProp = 'ref',
  innerRef,
}: FocusTrapProps)

export interface FocusTrapProps {
  /** Element to trap focus at, must support ref prop */
  children: any;

  /** If set to `false`, disables focus trap */
  active?: boolean;

  /** Prop that is used to access element ref @default 'ref' */
  refProp?: string;

  /** Ref to combine with the focus trap ref */
  innerRef?: React.Ref<any>;
}

Destructuring defaults in source

Only defaults written directly in parameter/props destructuring are listed. Conditional expressions, runtime theme and computed values require source inspection; this is not an exhaustive behavior-default list.

// FocusTrap
active = true

// FocusTrap
refProp = 'ref'

Native and external types

External types remain defined by React or native dependencies, not manually expanded into guessed props. The installed version's TypeScript definitions are authoritative.

React.Ref<any>