DocsComponents

Overlay

A dimmed backdrop for content that needs focus.

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/overlay.json https://react-toolbox.io/r/button.json

New here? Set up your project first. Styles, fonts, and required components are included. This example also installs Button for its trigger.

Usage

Click the backdrop or press Escape to close this example. Use Dialog or Drawer for modal content that also needs focus management; Overlay supplies the backdrop and scroll lock.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

Overlay visibility is controlled through active. Close it from your own click or Escape handler. lockScroll controls background scrolling while active.

Use Dialog or Drawer for a complete modal surface with its own keyboard and focus handling. Overlay is the lower-level backdrop building block.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`Overlay`

Property	Type	Default
`active`	`boolean`	`false`
`lockScroll`	`boolean`	`true`
`classNames`	`OverlayTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`OverlayTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ref`	`Ref<HTMLDivElement>`	`—`

Callbacks

Property	Type	Default
`onEscKeyDown`	`(event: KeyboardEvent) => void`	`—`

Also inherits HTMLAttributes<HTMLDivElement>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
overlay

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/overlay.

OverlayTheme

tsx

type OverlayTheme = Partial<Record<'active' | 'overlay', string>>;

OverlayClassNames

tsx

type OverlayClassNames = OverlayTheme;

OverlayProps

tsx

interface OverlayProps extends HTMLAttributes<HTMLDivElement> {
  active?: boolean;
  lockScroll?: boolean;
  onEscKeyDown?: (event: KeyboardEvent) => void;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: OverlayTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: OverlayTheme;
  ref?: Ref<HTMLDivElement>;
}

Material guidelines

A backdrop establishes separation between a modal surface and the underlying screen. It accompanies a dialog or temporary drawer rather than being a standalone task.
Prefer Dialog or Drawer for complete modal interactions. A custom composition must provide an accessible name, focus containment, and a clear dismissal path.

Material Design 1: Dialogs