Focus Guards - Radix UI Primitives

Auto-generate your docs

FocusGuards injects a pair of invisible, focusable elements at the start and end of the document body. These “guards” ensure that focusin and focusout events can be captured consistently, which is essential for focus management in complex UIs.

Installation

npm install @radix-ui/react-focus-guards

Components

FocusGuards

A component that renders its children and ensures focus guards are present in the document.

interface FocusGuardsProps {
  children?: React.ReactNode;
}

Hook

useFocusGuards

A hook that ensures focus guards are injected without needing to render a component.

function useFocusGuards(): void

Usage

Basic Component Usage

import { FocusGuards } from '@radix-ui/react-focus-guards';
import { FocusScope } from '@radix-ui/react-focus-scope';

function Modal({ children }: { children: React.ReactNode }) {
  return (
    <FocusGuards>
      <FocusScope trapped>
        <div className="modal">
          {children}
        </div>
      </FocusScope>
    </FocusGuards>
  );
}

Using the Hook

import { useFocusGuards } from '@radix-ui/react-focus-guards';
import { FocusScope } from '@radix-ui/react-focus-scope';

function Dialog({ children }: { children: React.ReactNode }) {
  useFocusGuards();

  return (
    <FocusScope trapped>
      <div className="dialog">
        {children}
      </div>
    </FocusScope>
  );
}

App-level Setup

import { FocusGuards } from '@radix-ui/react-focus-guards';

function App() {
  return (
    <FocusGuards>
      <Router>
        <YourApp />
      </Router>
    </FocusGuards>
  );
}

With Multiple Modals

import { useFocusGuards } from '@radix-ui/react-focus-guards';
import { FocusScope } from '@radix-ui/react-focus-scope';

function ModalManager({ children }: { children: React.ReactNode }) {
  // Only one set of focus guards needed for multiple modals
  useFocusGuards();

  return <>{children}</>;
}

function App() {
  const [modal1Open, setModal1Open] = useState(false);
  const [modal2Open, setModal2Open] = useState(false);

  return (
    <ModalManager>
      <button onClick={() => setModal1Open(true)}>Open Modal 1</button>
      <button onClick={() => setModal2Open(true)}>Open Modal 2</button>
      
      {modal1Open && (
        <FocusScope trapped>
          <div>Modal 1 Content</div>
        </FocusScope>
      )}
      
      {modal2Open && (
        <FocusScope trapped>
          <div>Modal 2 Content</div>
        </FocusScope>
      )}
    </ModalManager>
  );
}

Conditional Focus Management

import { useFocusGuards } from '@radix-ui/react-focus-guards';

function ConditionalDialog({ isOpen, children }: { 
  isOpen: boolean; 
  children: React.ReactNode;
}) {
  // Guards only injected when component is mounted
  useFocusGuards();

  if (!isOpen) return null;

  return (
    <div className="dialog">
      {children}
    </div>
  );
}

How It Works

Focus guards are invisible <span> elements with these properties:

data-radix-focus-guard attribute for identification
tabIndex={0} to make them focusable
Positioned fixed with zero opacity (invisible but functional)
No pointer events
Inserted at document.body edges (afterbegin and beforeend)

The guards ensure:

Focus events bubble correctly through the document
Focus trapping can detect when focus leaves the trapped area
Tab navigation at document boundaries works consistently

Reference Counting

The implementation uses reference counting:

Each call to useFocusGuards() increments an internal counter
Guards are only removed when the counter reaches zero
Multiple components can safely use focus guards simultaneously
Guards are shared across all instances (only one pair exists)

Implementation Details

function createFocusGuard() {
  const element = document.createElement('span');
  element.setAttribute('data-radix-focus-guard', '');
  element.tabIndex = 0;
  element.style.outline = 'none';
  element.style.opacity = '0';
  element.style.position = 'fixed';
  element.style.pointerEvents = 'none';
  return element;
}

The hook:

Checks for existing guards on mount
Creates new guards if none exist
Inserts them at document body edges
Increments the reference counter
Decrements counter and removes guards on unmount (if counter reaches 0)

When to Use

Use focus guards when:

Implementing focus trapping (modals, dialogs)
Building focus management utilities
Working with FocusScope or similar components
Need reliable focus event capture across the document

Notes

Focus guards are automatically shared across all components that use them. You don’t need to worry about duplicate guards - the implementation ensures only one pair exists in the document.

The guards are completely invisible and non-interactive to users. They exist purely to ensure browser focus events work correctly for JavaScript-based focus management.

If you’re using FocusScope or other Radix UI components that handle focus, you typically need focus guards. Many Radix primitives handle this automatically.

The reference counting ensures guards remain in the document as long as any component needs them, and are only removed when no components require them anymore.

⌘I

​Installation

​Components

​FocusGuards

​Hook

​useFocusGuards

​Usage

​Basic Component Usage

​Using the Hook

​App-level Setup

​With Multiple Modals

​Conditional Focus Management

​How It Works

​Reference Counting

​Implementation Details

​When to Use

​Notes

Installation

Components

FocusGuards

Hook

useFocusGuards

Usage

Basic Component Usage

Using the Hook

App-level Setup

With Multiple Modals

Conditional Focus Management

How It Works

Reference Counting

Implementation Details

When to Use

Notes