ModalBoundary

Renders a custom dialog with its own FocusBoundary, dismissed by the Back key

import { ModalBoundary } from "@roku-sdk/navigation";

ModalBoundary(props: IModalBoundaryProps): JSX.Element

Description

Renders a custom dialog with its own FocusBoundary, dismissed by the Back key.

Set dismissKeys to dismiss on other keys instead. Render it as a sibling of the content it covers, under a common ancestor FocusBoundary, and drive it with useModal, which owns the show state and moves focus into the dialog when it opens. If the dialog has focusable children, such as Confirm and Cancel buttons, pass initialFocus. If it has none, such as a help overlay, omit initialFocus and a hidden focus target is added for you.

Parameters

Name	Type	Description
`props`	IModalBoundaryProps	Visibility, focus identity, dismissal and dialog content.

Example

const help = useModal();

<ModalBoundary show={help.isOpen()} focusId={help.focusId} onDismiss={help.close} dim>
  <label text="Help content..." />
</ModalBoundary>

Types

IModalBoundaryProps

Props for the ModalBoundary component.

Name	Type	Description
`children?`	`Element`	The dialog's visual content (and, in Case 1, its focusable children).
`dim?`	`string \| boolean`	Simple scrim behind the dialog. `true` uses the default dark overlay (`0x000000AA`); a string sets a custom color/opacity; `false`/`undefined` renders no scrim. Ignored when `scrim` is provided.
`dismissKeys?`	`RemoteKeyName[]`	Remote key names that dismiss the modal, wired to the inner boundary's `onUnhandledKey`. Each fires `onDismiss` on key-down.
`focusId?`	`object`	The stable focus identity for the modal's inner `FocusBoundary`. See below.
`initialFocus?`	`object`	Focus target for Case 1 (dialogs whose children own focus). When provided, no dummy focusable is injected and this ref is used as the inner boundary's `initialFocus`. When omitted, a hidden dummy focusable is injected and used as `initialFocus` instead (Case 2).
`navigation?`	`"vertical" \| "horizontal" \| "grid"`	Navigation direction for the inner `FocusBoundary` (Case 1 button rows are typically `"horizontal"`). Ignored for content-only overlays.
`onDismiss?`	`() => void`	Called when the modal should be dismissed (a `dismissKeys` key was pressed).
`scrim?`	`() => Element`	Render prop for a fully custom scrim (blur, gradient, animated overlay). Overrides `dim` when provided.
`show`	`boolean`	Whether the modal is visible. Drive this from `useModal().isOpen`.

IModalBoundaryProps.focusId

The stable focus identity for the modal's inner FocusBoundary. Must match the focusId returned by (or passed to) the paired useModal call so open() can transfer focus here via setFocus.

If omitted, an internal identity is generated — but the parent then has no way to reference it for setFocus, so prefer passing useModal().focusId.