Skip to content

Design system

Documentation

DesignComponents / Alert

Components / Alert

Beta

Alert

Use Alert for an important message that belongs beside the content it affects.

On this page

Examples

Feedback variants

Each semantic variant combines a readable message with the matching status color and announcement role.

New report available

The monthly report is ready to review.

Changes saved

Workspace settings were updated.

Review required

Two members still need to accept their invitations.

Info, success, warning, and danger alerts

Dismissible feedback

Dismissal is a local presentation behavior. A controlled parent can keep or remove the alert through open and onOpenChange.

Invitation prepared

The invitation is ready to send.

Dismissible success alert

Try the props

Compare semantic meaning and optional dismissal using the same values in the preview and copied code.

Review required

Check the pending items before continuing.

Alert property playground

When to use

Use Alert for feedback that must remain visible in the current page or form section. Use Toast for brief, non-blocking feedback that should not take space in the content flow.

Usage

import { Alert } from "@phuctech/ui/components/alert";

<Alert variant="danger" heading="Import failed" description="Check the file format and try again." />

Variant is one of info, success, warning, and danger. The component performs no data requests and does not decide whether a business operation succeeded.

API

Component API
PropTypeDefaultDescriptionConstraints
variant"info" | "success" | "warning" | "danger""info"Semantic visual treatment and default announcement role.Always include readable text; danger uses role=alert and the other variants use role=status by default.
headingReactNode—Optional concise heading before the message.Keep the heading specific to the affected task.
descriptionReactNode—Explanatory message shown below the heading when present.Provide a recovery step for errors where one is known.
iconReactNode | nullvariant iconReplaces the built-in icon; null removes it.Decorative icons are hidden from assistive technology.
dismissiblebooleanfalseShows a named dismiss button.Use only when the message may be safely hidden.
openbooleanuncontrolledControlled visibility.When supplied, pair state changes with onOpenChange.
defaultOpenbooleantrueInitial visibility when open is omitted.Applies to uncontrolled use.
onOpenChange(open: boolean) => void—Receives a visibility request, including dismissal.The parent owns visibility when open is controlled.
dismissLabelstring"Dismiss alert"Accessible name for the dismiss button.Use a more specific label when multiple alerts can be dismissed.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-info-*, --color-success-*, --color-warning-*, --color-danger-*Semantic stateBackground, border, and text rolesKeeps state colors consistent across light and dark themes.
--size-icon-md / --size-icon-smIcon sizing16px / 14pxAligns the status and dismiss icons with the shared icon scale.
--radius-lgSurface geometry10pxMatches the shared medium content surface.

Accessibility

  • The default live-region role is status for info, success, and warning, and alert for danger. Pass a native role when the surrounding interaction needs a different announcement contract.
  • The status icon is decorative; the words carry the meaning. The dismiss control has a configurable accessible name.
  • Do not rely on color alone, and keep dismissal keyboard-operable through the shared Button behavior.

Do and don’t

Do

Explain what happened and give a recovery step for a blocking issue.

Don’t

Use Alert as a replacement for form validation or a temporary Toast message.

  • Toast displays transient feedback outside the page flow.
  • Field connects validation messages to individual controls.