or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

focus-control-hooks.mdfocus-lock-components.mdindex.mdtypescript-types.md
tile.json

tessl/npm-react-focus-lock

React focus management library that provides robust focus trapping functionality for modal dialogs and accessibility compliance

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-focus-lock@2.13.x

To install, run

npx @tessl/cli install tessl/npm-react-focus-lock@2.13.0

index.mddocs/

React Focus Lock

React Focus Lock is a comprehensive focus management library that provides robust focus trapping functionality for React applications, primarily designed for modal dialogs, dropdown menus, and other UI components that require focus containment. The library implements accessibility-compliant focus management by automatically trapping keyboard focus within a designated area, preventing users from tabbing out of modal dialogs or other focused components while maintaining proper tab order.

Package Information

  • Package Name: react-focus-lock
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install react-focus-lock

Core Imports

import FocusLock from "react-focus-lock";

For accessing all components and hooks:

import FocusLock, {
  AutoFocusInside,
  MoveFocusInside,
  FreeFocusInside,
  InFocusGuard,
  useFocusScope,
  useFocusController,
  useFocusState,
  useFocusInside
} from "react-focus-lock";

Alternative entry points:

// UI components only (requires sidecar)
import { FocusLockUI } from "react-focus-lock/UI";

// Sidecar for custom integrations
import sidecar from "react-focus-lock/sidecar";

CommonJS:

const FocusLock = require("react-focus-lock");
const { AutoFocusInside, useFocusScope } = require("react-focus-lock");

Basic Usage

import React, { useState } from "react";
import FocusLock from "react-focus-lock";

function ModalDialog({ isOpen, onClose, children }) {
  if (!isOpen) return null;

  return (
    <div className="overlay">
      <FocusLock returnFocus>
        <div className="modal">
          {children}
          <button onClick={onClose}>Close</button>
        </div>
      </FocusLock>
    </div>
  );
}

// Usage
function App() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button onClick={() => setShowModal(true)}>Open Modal</button>
      <ModalDialog isOpen={showModal} onClose={() => setShowModal(false)}>
        <h2>Modal Content</h2>
        <input placeholder="Focused input" />
        <button>Modal Button</button>
      </ModalDialog>
    </div>
  );
}

Architecture

React Focus Lock is built around several key components:

  • Focus Lock Components: Main FocusLock component and related helper components for controlling focus behavior
  • Focus Control Hooks: React hooks for programmatic focus management and state tracking
  • Sidecar Architecture: Split UI and logic for optimized bundle sizes
  • TypeScript Integration: Full type safety with comprehensive interface definitions
  • Accessibility Compliance: WAI-ARIA compliant focus management with cross-frame support

Capabilities

Focus Lock Components

Core React components for implementing focus trapping, including the main FocusLock component and helper components for specific focus behaviors.

declare const FocusLock: FC<ReactFocusLockProps>;

interface ReactFocusLockProps {
  disabled?: boolean;
  returnFocus?: boolean | FocusOptions | ((returnTo: Element) => boolean | FocusOptions);
  autoFocus?: boolean;
  children?: ReactNode;
}

Focus Lock Components

Focus Control Hooks

React hooks for programmatic focus management, providing fine-grained control over focus behavior within and outside of focus locks.

function useFocusScope(): FocusControl;
function useFocusController<Elements extends HTMLElement = HTMLElement>(
  ...shards: ReadonlyArray<HTMLElement | { current: HTMLElement | null }>
): FocusControl;

interface FocusControl {
  autoFocus(): Promise<void>;
  focusNext(options?: FocusOptions): Promise<void>;
  focusPrev(options?: FocusOptions): Promise<void>;
}

Focus Control Hooks

TypeScript Types and Interfaces

Complete type definitions for all components, hooks, and configuration options, ensuring full type safety in TypeScript projects.

interface FocusOptions {
  cycle?: boolean;
  onlyTabbable?: boolean;
}

interface FocusControl {
  autoFocus(): Promise<void>;
  focusNext(options?: FocusOptions): Promise<void>;
  focusPrev(options?: FocusOptions): Promise<void>;
  focusFirst(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
  focusLast(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
}

TypeScript Types