Skip to content
THE COMPONENT LIBRARY
Skip to content

Component reference

FocusScope

An inline confirmation with deliberate focus handling.

Preview

Live preview

Changes apply to this preview only.

Inline confirmation

A non-modal confirmation that still owns the keyboard while it is open.

DraftUnsaved changes in the editor.
Publish the draft and notify the team?
The confirmation can wrap the actions in a FocusScope and set active while it is open; the page behind it stays interactive.

Skip link target

Pair a focus scope with a skip link to move keyboard users into the main content.

A skip link focuses the main region; the scope then keeps Tab inside until the user leaves it deliberately.
Main contentAn inactive scope renders no trap and leaves the normal page order intact.

Drawer body

The same scope can live inside a drawer without importing the drawer.

SettingsFocus returns to the menu button on close.

Width adapts to the available space

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Playground

Activate the scope, then use Tab and Shift+Tab. Deactivate it to see the restore behavior.

Open preview

Container focus

Explore container focus with FocusScope.

Open preview

Skip link target

A skip link target composition using FocusScope.

Open preview

Usage

Use a scope only when the interaction calls for managed focus; avoid trapping ordinary page content.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluFocusScopeProps

Type source
PimoluFocusScopeProps public API
NameTypeDefaultDescription
asElementType | undefined`div`Element rendered by the scope. Defaults to `div`.
activeboolean | undefined`true`Enables the scope: focus moves inside on activation, and is restored on deactivation (see `restoreFocus`). When false, nothing happens. Defaults to `true`.
trappedboolean | undefined`true`Keep Tab and Shift+Tab inside the scope. Set it to false for a scope that only owns the initial focus. Defaults to `true`.
restoreFocusboolean | undefined`true`Return focus to the element focused before activation. When false, focus stays wherever it is when the scope deactivates. Defaults to `true`.
initialFocusPimoluFocusScopeInitialFocus | undefined`first`Focus the first focusable child, or the container itself (useful when the scope holds no interactive control yet). Defaults to `first`.
defaultValuestring | number | readonly string[] | undefined—Standard React/HTML attribute.
classNamestring | undefined—Standard React/HTML attribute.
styleCSSProperties | undefined—Standard React/HTML attribute.
aria-labelstring | undefined—Defines a string value that labels the current element.
childrenReactNode—Standard React/HTML attribute.
onChangeChangeEventHandler<HTMLElement, Element> | undefined—Standard React/HTML attribute.
onClickMouseEventHandler<HTMLElement> | undefined—Standard React/HTML attribute.
as

ElementType | undefined

Default: `div`

Element rendered by the scope. Defaults to `div`.

active

boolean | undefined

Default: `true`

Enables the scope: focus moves inside on activation, and is restored on deactivation (see `restoreFocus`). When false, nothing happens. Defaults to `true`.

trapped

boolean | undefined

Default: `true`

Keep Tab and Shift+Tab inside the scope. Set it to false for a scope that only owns the initial focus. Defaults to `true`.

restoreFocus

boolean | undefined

Default: `true`

Return focus to the element focused before activation. When false, focus stays wherever it is when the scope deactivates. Defaults to `true`.

initialFocus

PimoluFocusScopeInitialFocus | undefined

Default: `first`

Focus the first focusable child, or the container itself (useful when the scope holds no interactive control yet). Defaults to `first`.

defaultValue

string | number | readonly string[] | undefined

No default extracted.

Standard React/HTML attribute.

className

string | undefined

No default extracted.

Standard React/HTML attribute.

style

CSSProperties | undefined

No default extracted.

Standard React/HTML attribute.

aria-label

string | undefined

No default extracted.

Defines a string value that labels the current element.

children

ReactNode

No default extracted.

Standard React/HTML attribute.

onChange

ChangeEventHandler<HTMLElement, Element> | undefined

No default extracted.

Standard React/HTML attribute.

onClick

MouseEventHandler<HTMLElement> | undefined

No default extracted.

Standard React/HTML attribute.

Accessibility

  • Check the initial focus target, Tab boundaries, Escape handling and restoration.
Read the accessibility guide →