tessl/npm-react-focus-lock

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

React Focus Lock

Name: tessl/npm-react-focus-lock
Author: tessl

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

Install with Tessl CLI