Busy Indicator

A busy indicator blocks interaction with a fullscreen or inline region while a longer-running process completes.

Usage

forge-busy-indicator blocks interaction with a region through open, mode (fullscreen or inline), and variant (spinner, progress, or message-only), plus optional titleText, message, and cancelable. Use it for an operation expected to take more than a second that genuinely needs to block the user, on either the whole page or a single component. For a shorter, purely visual loading cue, use a circular progress or linear progress indicator instead, and for a page’s initial load where the eventual layout is already known, use a skeleton instead.

Rules

Use a busy indicator only for an operation expected to take more than a second.

Word the message as "[Object] is being [operation]" so the user knows exactly what's happening.

Set cancelable when the operation can genuinely be interrupted, and leave it off otherwise.

Don't

Don't use a busy indicator for a near-instant operation — a linear or circular progress indicator alone is enough.

Don't block the whole page with mode="fullscreen" for a change scoped to a single component — use mode="inline" instead.

Don't leave a busy indicator on screen with no message when the wait might run long.

Busy indicators communicate to the user that an operation is in progress and blocks interaction with the page or a specific region of it.

import "@tylertech/forge/busy-indicator";

Properties

Property	Attribute	Type	Default	Description
`open`	—	`boolean`	`false`	Indicates whether the busy indicator is open.
`mode`	—	`BusyIndicatorMode`	`'fullscreen'`	Whether the busy indicator is fullscreen or inline.
`titleText`	—	`string \| undefined`	—	The title text to display.
`headingLevel`	—	`HeadingLevel`	`1`	The heading level for the title.
`message`	—	`string \| undefined`	—	The message to display.
`label`	—	`string \| undefined`	—	The accessible label for dialog.
`description`	—	`string \| undefined`	—	The accessible description for dialog.
`cancelable`	—	`boolean`	`false`	Indicates whether the cancel button is displayed.
`variant`	—	`BusyIndicatorVariant`	`'spinner'`	The variant of the busy indicator. - `spinner` (default): displays a spinner. - `progress`: displays a progress bar. - `message-only`: No progress indicator is displayed.
`determinate`	—	`boolean`	`false`	Indicates whether the loading indicator is determinate.
`progress`	—	`number`	`0`	The progress amount for the progress bar.
`buffer`	—	`number`	`0`	The buffer amount for the progress bar.
`transparent`	—	`boolean`	`false`	Indicates whether the busy indicator surface should be transparent (no background or elevation).

Events

Name	Type	Description
`forge-busy-indicator-cancel`	`CustomEvent<void>`	Fired when the cancel button is clicked.

Slots

Name	Description
`title`	The title text to display.
`message`	The message to display.
`cancel-text`	The text for the cancel button.

Accessibility documentation coming soon.