Notification Block

A Notification Block explains a problem that prevents the user from using a page, such as a missing permission or an unexpected error, and offers a way forward.

Import#

import { NotificationBlock } from '@volue/wave-react';

Notification Block is a compound component made up of several parts:

NotificationBlock.Root: The wrapper that contains all the parts of a notification block.
NotificationBlock.Title: The title, with an error icon before it. Renders an h2 by default.
NotificationBlock.Description: The supporting text that explains the problem.
NotificationBlock.Details: The wrapper for optional, collapsible technical details.
NotificationBlock.DetailsTrigger: The button that toggles the technical details.
NotificationBlock.DetailsPanel: The collapsible content with the technical details.
NotificationBlock.Actions: The container for the actions that offer a way forward.

When to use#

Use a Notification Block when a problem blocks the whole page, for example when the user is missing a permission or the app hits an unexpected error. It replaces the page content, explains what happened, and offers a way forward.

For problems that don't block the whole page, use one of the other notification components instead.

Render it in AppFrame.Main with centerContent, so it replaces the page content and sits in the middle of the main area. See In App Frame.

Examples#

Basic#

A title, a description, and the actions that let the user move on.

In App Frame#

Show the block in place of the page content: put it in AppFrame.Main with centerContent.

See the system feedback demo in Storybook for a complete flow with loading and tenant switching.

Alternative actions#

When actions are alternatives to each other, such as switching to another tenant or logging out, separate them with muted text such as "or".

Technical details#

Tuck technical information, such as the failed request or an error ID, behind NotificationBlock.Details. Put a NotificationBlock.DetailsTrigger and a NotificationBlock.DetailsPanel inside it. Inline <code> elements in the panel are highlighted.

The trigger has no default text, so pass a translated label. NotificationBlock.Details accepts the same state props as Collapsible.

Accessibility#

When the block appears because of the user's action, such as a navigation or a tenant switch, set focusOnMount on NotificationBlock.Title, so screen reader and keyboard users land on it. Don't use it on a full page load, or for failures the user didn't trigger.
NotificationBlock.Title renders an h2 by default. Use the as prop to fit it into your page's heading order.
NotificationBlock.DetailsTrigger exposes aria-expanded and aria-controls, so assistive technologies know the state of the details and which content they control.

API reference#

NotificationBlock.Root#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value

NotificationBlock.Title#

In addition to the props below, you can pass Heading props, except variant.

Prop	Type	Default
`as`	`enum`	`h2`
`css`	`StitchesCss`	No default value
`focusOnMount`	`boolean`	`false`

NotificationBlock.Description#

In addition to the props below, you can pass Text props.

Prop	Type	Default
`as`	`enum`	`p`
`css`	`StitchesCss`	No default value

NotificationBlock.Details#

Prop	Type	Default
`css`	`StitchesCss`	No default value
`isOpen`	`boolean`	`false`
`defaultIsOpen`	`boolean`	No default value
`onIsOpenChange`	`function`	No default value

NotificationBlock.DetailsTrigger#

In addition to the props below, you can pass native button props.

Prop	Type	Default
`css`	`StitchesCss`	No default value

NotificationBlock.DetailsPanel#

In addition to the props below, you can pass Collapsible.Panel props.

Prop	Type	Default
`css`	`StitchesCss`	No default value
`unmountOnExit`	`boolean`	`false`
`startingHeight`	`string \| number`	No default value

NotificationBlock.Actions#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value