v6.0.35

use-focus-trap

Trap focus inside given node
Import
Source
View source code
Docs
Edit this page
Package
@asuikit/hooks

Usage

use-focus-trap traps focus at given node, for example in modal, drawer or menu. Node must include at least one focusable element. When node unmounts, focus trap is automatically disabled.

import { useFocusTrap } from '@asuikit/hooks';


function Demo() {
  const focusTrapRef = useFocusTrap();


  return (
    <div ref={focusTrapRef}>
      <input />
    </div>
  );
}

API

Hook accepts focus trap active state as single argument:

useFocusTrap(); // -> focus trap inactive
useFocusTrap(true); // -> focus trap active


useFocusTrap(false); // -> focus trap disabled

Hook returns ref that should be passed to dom node:

const focusTrapRef = useFocusTrap();


// With regular element:
<div ref={focusTrapRef} />


// With Mantine component:
<Paper ref={focusTrapRef} />

Combine with other ref based hooks

Usually focus trap is not used alone. To combine use-focus-trap hook with other ref based hooks use use-merged-ref hook:

import { useRef } from 'react';
import { useClickOutside, useFocusTrap, useMergedRef } from '@asuikit/hooks';


function Demo() {
  const myRef = useRef();
  const useClickOutsideRef = useClickOutside(() => {});
  const focusTrapRef = useFocusTrap();
  const mergedRef = useMergedRef(myRef, useClickOutsideRef, focusTrapRef);


  return <div ref={mergedRef} />;
}

Initial focus

By default, focus trap will move focus to first interactive element. To specify element that should receive initial focus add data-autofocus attribute, note that focus trap works with dom and this attribute should be added to element:

import { useFocusTrap } from '@asuikit/hooks';


function Demo() {
  const focusTrapRef = useFocusTrap();


  return (
    <div ref={focusTrapRef}>
      <input />
      {/* Second input in modal will have initial focus */}
      <input data-autofocus />
      <input />
    </div>
  );
}

Examples

use-focus-trap is used in some Mantine components: Modal, Drawer, Menu and others.

Modal example – when modal is opened focus is trapped inside:

Menu example – when menu is opened focus is trapped inside and Tab key is disabled:

Definition

function useFocusTrap(active?: boolean): (instance: HTMLElement) => void;
Go back
use-focus-return – @asuikit/hooks
Up next
use-focus-within – @asuikit/hooks
Build fully functional accessible web applications faster than ever
About
ContributeAbout MantineChangelogReleases
Community
Chat on DiscordFollow on TwitterFollow on GitHubGitHub discussions
Project
Mantine UIDocumentationGitHub organizationnpm organization
Built by Vitaly Rtishchev and these awesome people
Join Discord community
Follow Mantine on Twitter