Focus Trap

Component that traps focus within a DOM node. A focus trap ensures that tab and shift + tab keys will cycle through the focus trap's tabbable elements but not leave the focus trap. This is great for making accessible modals.

install	version	usage
yarn add @ciceksepeti/cui-focus-trap	1.0.0	import {FocusTrap} from '@ciceksepeti/cui-focus-trap'

Wai-AriaW3

RepositoryGitHub

PackageNPM

Content

FocusTrap component traps focus events inside of its boundaries. It is developed according to the accessibility rules. User cannot leave the trap boundaries unless disables it. Great match for components like Modals, Dialogs and etc. FocusTrap is a polymorphic component. That's why can be rendered as any valid HTML tag.

Example

Default

Example of a default behavior of FocusTrap component. Renders as 'div' by default.

import React from 'react';
import FocusTrap from '@ciceksepeti/cui-focus-trap';

export const Example = () => {
  return (
    <FocusTrap as="div" autoFocusToFirst restoreFocusOnUnmount>
      <button>focusable</button>
      <button>focusable</button>
      <button>focusable</button>
      <button disabled>disabled</button>
      <span>
        <button>hidden</button>
        <button tabIndex={-1}>tabindex -1</button>
      </span>
      <button>focusable</button>
    </FocusTrap>
  );
};

PREVIEW

Focus Trap Default

// Click here and press the tab button to see the focus trap how it works.

Refocus On Unmount

Example of refocusing the last focused element when FocusTrap unmounts.

import React, { useState } from 'react';
import FocusTrap from '@ciceksepeti/cui-focus-trap';

export const Example = () => {
  const buttonStyles = {
    padding: '5px',
    margin: '3px 5px',
    cursor: 'pointer',
  };
  const args = {
    as: 'div',
    disabled: false,
    autoFocusToFirst: true,
    autoFocusToLast: false,
    restoreFocusOnUnmount: true,
  };

  const [open, setOpen] = useState(false);

  return (
      <button style={buttonStyles}>some button</button>
      <button style={buttonStyles} onClick={() => setOpen(true)}>
        show panel
      </button>
      <button style={buttonStyles}>some button</button>
      {open && (
        <div
          style={{
            padding: 10,
            borderRadius: 4,
            margin: '10px 5px',
            border: '1px solid red',
          }}
        >
          <FocusTrap {...args}>
            <h3 style={{ marginTop: 0 }}>Trapped Panel</h3>
            <button style={buttonStyles}>focusable</button>
            <button style={buttonStyles}>focusable</button>
            <button style={buttonStyles} onClick={() => setOpen(false)}>
              Close panel
            </button>
          </FocusTrap>
        </div>
      )}
  );
};

PREVIEW

Focus Trap Refocus

autoFocus Attribute

Example of auto focusing to element with autoFocus attribute.

import React from 'react';
import FocusTrap from '@ciceksepeti/cui-focus-trap';

export const CUIFocusTrapAutoFocus = () => {
  const buttonStyles = {
    padding: '5px',
    margin: '3px 5px',
    cursor: 'pointer',
  };
  const args = {
    as: 'div',
    disabled: false,
    autoFocusToFirst: true,
    autoFocusToLast: false,
    restoreFocusOnUnmount: true,
  };

  return (
    <FocusTrap {...args}>
      <button style={buttonStyles}>focusable</button>
      // autoFocus attribute is false
      <button style={buttonStyles} autoFocus={false}></button>
      <button style={buttonStyles}>focusable</button>
    </FocusTrap>
  );
};

PREVIEW

Focus Trap Autofocus

Props

Name	Type	Default	Required	Description
as	string	div	-	Changes html tag of focusTrap component which renders to DOM
disabled	boolean	false	-	Disables all trap features
autoFocusToFirst	boolean	true	-	Auto focuses to first focusable child of focus trap.
autoFocusToLast	boolean	false	-	auto focuses to last focusable child of focus trap.
restoreFocusOnUnmount	boolean	true	-	Refocuses to last focused element when focus trap is unmounted
children	React.ReactNode		required	The content you want to be wrapped by focus trap.

Playground