Required Action Dialog

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import RequiredActionDialog, RequiredActionDialogBehavior and RequiredActionIntent from @prepared911/ui/blocks/required-action-dialog. The declaration in packages/ui/src/blocks/required-action-dialog/schema.ts is the contract for inputs and composed components; prop types and TSDoc are in packages/ui/src/blocks/required-action-dialog/props.ts.

Prop	Type	Default
`open`	`boolean`, required. Only the host changes it
`title`	`LocalizedMessage`, required
`description`	`LocalizedMessage`, required
`primaryAction`	`RequiredAction`, required in both behaviors
`secondaryActions`	`readonly RequiredAction[]`, placed before the primary	none
`behavior`	`RequiredActionDialogBehavior`: `Dismissible` or `Forced`. `Forced` is the rare exception	`Dismissible`
`closeLabel`	`LocalizedMessage`, required when `Dismissible`; rejected when `Forced`
`onOpenChange`	`(open: false, details) => void`, `Dismissible` only; reasons `close-press`, `close-request`	none
`errorCode`	`DisplayValue`; needs `errorCodeLabels`	none
`errorCodeLabels`	`RequiredActionErrorCodeLabels`; needs `errorCode`	none

A RequiredAction is { label: LocalizedMessage; onPress: () => void | Promise<void>; intent?: RequiredActionIntent }. RequiredActionIntent is Default or Destructive (only for an action that is itself irreversible). Forced is the rare exception, for a condition the person cannot safely continue past (for example a forced logout). Dismissible is the default and the right choice unless there is no safe way to continue. Never use Forced to make an ordinary notification harder to ignore; the host owns closing it, so it must always provide a way to complete the required action.

Props

Name	Type	Default	Description
`description`	`LocalizedMessage`	—	What happened and what the person must do. Describes the dialog.
`open`	`boolean`	—	Whether the dialog is shown. Only the host changes it, in both behaviors: a close request is reported, never applied, and there is no `defaultOpen` or trigger.
`primaryAction`	`RequiredAction`	—	The action the person is expected to take, required in both behaviors. It takes initial focus and sits last, at the inline end.
`title`	`LocalizedMessage`	—	Heading that names the dialog. Always visible.
`behavior`	`RequiredActionDialogBehavior`	`RequiredActionDialogBehavior.Dismissible`	The default and the right choice unless there is no safe way to continue. Set {@link RequiredActionDialogBehavior.Forced} only for the rare condition the person cannot safely continue past. The rare exception, for a condition the person cannot safely continue past, such as a forced logout. It must not be used to make an ordinary notification harder to ignore. The host owns closing it, so it must always provide a way to complete the required action. Use the default {@link RequiredActionDialogBehavior.Dismissible} otherwise.
`closeLabel`	`LocalizedMessage`	—	Accessible name of the header close control, such as "Close". The control shows only an icon. Absent in this behavior: there is no close control to name.
`errorCode`	`DisplayValue`	—	Absent in this shape: an error code comes with its labels, or neither is set. A code the person can read out to support. Data, not copy: shown as written, with a copy button.
`errorCodeLabels`	`RequiredActionErrorCodeLabels`	—	Absent in this shape: error code labels come with an error code, or neither is set. The visible and accessible copy for the error code row.
`onOpenChange`	`((open: false, details: DialogOpenChangeDetails) => void)`	—	Called when the person closes the dialog without acting: `close-press` for the close control, `close-request` for Escape. The dialog stays open until the host sets `open` to `false`. The action is still required: the host decides when the dialog comes back. Absent in this behavior: the person cannot close the dialog, so there is nothing to report.
`secondaryActions`	`readonly RequiredAction[]`	—	Other ways forward, in reading order before the primary action. Omit it when there is one way forward.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Required Action Dialog / Usage

Required Action Dialog / Accessibility

On this page

Props

Storybook

Required Action Dialog

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Prop	Type	Default
`open`	`boolean`, required. Only the host changes it
`title`	`LocalizedMessage`, required
`description`	`LocalizedMessage`, required
`primaryAction`	`RequiredAction`, required in both behaviors
`secondaryActions`	`readonly RequiredAction[]`, placed before the primary	none
`behavior`	`RequiredActionDialogBehavior`: `Dismissible` or `Forced`. `Forced` is the rare exception	`Dismissible`
`closeLabel`	`LocalizedMessage`, required when `Dismissible`; rejected when `Forced`
`onOpenChange`	`(open: false, details) => void`, `Dismissible` only; reasons `close-press`, `close-request`	none
`errorCode`	`DisplayValue`; needs `errorCodeLabels`	none
`errorCodeLabels`	`RequiredActionErrorCodeLabels`; needs `errorCode`	none

Props

Name	Type	Default	Description
`description`	`LocalizedMessage`	—	What happened and what the person must do. Describes the dialog.
`open`	`boolean`	—	Whether the dialog is shown. Only the host changes it, in both behaviors: a close request is reported, never applied, and there is no `defaultOpen` or trigger.
`primaryAction`	`RequiredAction`	—	The action the person is expected to take, required in both behaviors. It takes initial focus and sits last, at the inline end.
`title`	`LocalizedMessage`	—	Heading that names the dialog. Always visible.
`behavior`	`RequiredActionDialogBehavior`	`RequiredActionDialogBehavior.Dismissible`	The default and the right choice unless there is no safe way to continue. Set {@link RequiredActionDialogBehavior.Forced} only for the rare condition the person cannot safely continue past. The rare exception, for a condition the person cannot safely continue past, such as a forced logout. It must not be used to make an ordinary notification harder to ignore. The host owns closing it, so it must always provide a way to complete the required action. Use the default {@link RequiredActionDialogBehavior.Dismissible} otherwise.
`closeLabel`	`LocalizedMessage`	—	Accessible name of the header close control, such as "Close". The control shows only an icon. Absent in this behavior: there is no close control to name.
`errorCode`	`DisplayValue`	—	Absent in this shape: an error code comes with its labels, or neither is set. A code the person can read out to support. Data, not copy: shown as written, with a copy button.
`errorCodeLabels`	`RequiredActionErrorCodeLabels`	—	Absent in this shape: error code labels come with an error code, or neither is set. The visible and accessible copy for the error code row.
`onOpenChange`	`((open: false, details: DialogOpenChangeDetails) => void)`	—	Called when the person closes the dialog without acting: `close-press` for the close control, `close-request` for Escape. The dialog stays open until the host sets `open` to `false`. The action is still required: the host decides when the dialog comes back. Absent in this behavior: the person cannot close the dialog, so there is nothing to report.
`secondaryActions`	`readonly RequiredAction[]`	—	Other ways forward, in reading order before the primary action. Omit it when there is one way forward.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Required Action Dialog / Usage

Required Action Dialog / Accessibility

On this page

Props

Storybook