Skip to content
Browse documentation
whisk/ui

Alert

Communicate an important status in context.

Overview

Alert keeps important status information visible in the part of the page it affects. Its visual treatment is separate from announcement, dismissal, and focus policy, which the application owns.

Use when

An important status or next step should remain visible in context.

Use instead

Use Toast for short-lived completion feedback or Field error text for one control's validation.

Usage

Saved

Your changes are now active.

import { Alert, Text } from "@smoothie-framework/whisk-react";

<Alert variant="success" title="Saved">
  <Text>Your changes are now active.</Text>
</Alert>

Examples

Choose a visual treatment

Use the variant for the status meaning and appearance for the surface emphasis. Neither prop creates a live region.

Deployment scheduled

The release starts at 14:00 UTC.

Review needed

Two members still need access.

Could not save

Check the connection and try again.

import { Alert, Stack, Text } from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Alert variant="info" appearance="surface" indicator title="Deployment scheduled">
    <Text>The release starts at 14:00 UTC.</Text>
  </Alert>
  <Alert variant="warning" appearance="outline" indicator title="Review needed">
    <Text>Two members still need access.</Text>
  </Alert>
  <Alert variant="error" appearance="solid" indicator title="Could not save">
    <Text>Check the connection and try again.</Text>
  </Alert>
</Stack>

Announce a new update deliberately

Alerts are silent by default. Use a polite status update when a new non-urgent result appears after an action.

Project saved

Your changes are now active.

import { Alert, Text } from "@smoothie-framework/whisk-react";

<Alert
  variant="success"
  indicator
  role="status"
  aria-live="polite"
  title="Project saved"
>
  <Text>Your changes are now active.</Text>
</Alert>

Dismiss from application state

dismissible only renders a button and calls onDismiss. Keep the message visible until the application decides to remove it.

Review needed

Two members still need access.

import { useState } from "react";
import { Alert, Button, Text } from "@smoothie-framework/whisk-react";

export function AccessNotice() {
  const [visible, setVisible] = useState(true);

  return visible ? (
    <Alert
      variant="warning"
      indicator
      title="Review needed"
      dismissible
      dismissLabel="Dismiss notice"
      onDismiss={() => setVisible(false)}
    >
      <Text>Two members still need access.</Text>
    </Alert>
  ) : (
    <Button variant="secondary" onClick={() => setVisible(true)}>Show notice</Button>
  );
}

Keep recovery actions explicit

Alert has no action slot or built-in retry behavior. Place a real Button in the message when recovery must stay available.

Could not save

Check the connection, then try again.

import { useState } from "react";
import { Alert, Button, Stack, Text } from "@smoothie-framework/whisk-react";

export function SaveError() {
  const [retryRequested, setRetryRequested] = useState(false);

  return (
    <Alert variant="error" indicator title="Could not save">
      <Stack gap={3} align="start">
        <Text>
          {retryRequested
            ? "Retry requested. Keep the error visible until the request succeeds."
            : "Check the connection, then try again."}
        </Text>
        <Button variant="secondary" onClick={() => setRetryRequested(true)}>
          Try again
        </Button>
      </Stack>
    </Alert>
  );
}

Keep a quiet notice in context

A named Alert becomes a labelled group, not a live region. This is suitable for important context that is already present when the page loads.

Preview environment

Changes here do not affect production.

import { Alert, Text } from "@smoothie-framework/whisk-react";

<Alert
  variant="neutral"
  appearance="subtle"
  aria-label="Preview environment notice"
  title="Preview environment"
>
  <Text>Changes here do not affect production.</Text>
</Alert>

Props

Component props

PropTypeDefaultDescription
variantinfo | success | warning | error | neutralinfoChoose the visual status treatment. It does not set a live-region role.
appearancesubtle | surface | outline | solidsubtleChoose the visual emphasis for the message.
size | inlinesm | md | lg | booleanmd | falseSet the density, or make the alert fit its content inline.
indicator | iconboolean | ReactNodefalse | noneShow the default status icon or provide a decorative custom icon. Icons are hidden from assistive technology.
titleReactNodenoneAdd a visible, concise status heading. This is not an HTML tooltip.
childrenRenderablenoneProvide supporting context or next steps.
dismissible | onDismiss | dismissLabelboolean | () => void | stringfalse | required when dismissible | DismissRender a native dismiss button and notify the application. The application removes the Alert and manages focus after dismissal.
role | aria-live | aria-labelnative div attributesnoneOpt into announcement or name a labelled alert. A named Alert defaults to role=group; no live-region role is added automatically.

Accessibility

Alert renders a div and adds no live-region role, timer, focus movement, or hidden state. Visual severity never decides announcement urgency. Use role="status" with polite live-region behavior for a newly rendered non-urgent update, and reserve role="alert" for urgent errors that need immediate interruption. Do not make a static alert announced on every page load. A title or aria-label names the visible group, and the indicator is decorative. If an Alert is dismissible, it provides a native button with visible localizable text; remove the Alert in onDismiss and move focus only when removal would otherwise leave the user without a useful target. Keep an Alert in the page when the message or recovery action needs to remain available, and test live announcements with the assistive technologies your application supports.

Content guidance

Make the title state the status or required next step. Supporting text should explain the impact or recovery action without repeating the title.