Messages and feedback

Messages guide the user, confirm what happened and help them recover. They also interrupt, so every message has to earn its place.

Principles

1. First, try to remove the need for the message. A disabled button with a tooltip, a sensible default or a clearer label often does more than an error after the fact.
2. Interrupt only when the user must decide. Everything else is shown without stopping their work.
3. Help the user recognize, understand and fix the problem. Say what happened and what to do, next to where it happened.
4. Never rely on color alone. Pair status colors with text, and with an icon where space allows.

Choosing the component

Field validation

Validate when the user leaves a field and again on submit, not on every keystroke. Put the error under the field it belongs to, mark the control with aria-invalid, and move focus to the first invalid field on submit. The message says how to fix the value: “Enter a domain, such as acme.com.”, not “Invalid input.”

<Field data-invalid className="max-w-sm">
  <FieldLabel htmlFor="monitored-domain">Monitored domain</FieldLabel>
  <Input
    id="monitored-domain"
    defaultValue="https://acme"
    aria-invalid
    aria-describedby="monitored-domain-error"
  />
  <FieldError id="monitored-domain-error">
    Enter a domain without the protocol, such as acme.com.
  </FieldError>
</Field>

Toasts

A toast confirms the result of something the user just did, and goes away on its own.

• One toast per action. A bulk action raises one toast with the count, not one per item.
• Success toasts are short past-tense statements: “Rule created”.
• Use the toast type that matches the result: toast.success(), toast.info(), toast.warning(), toast.error(). Each takes the colors and icon of its type; a plain toast() is neutral.
• Do not put the only copy of an important error in a toast: it disappears. If the user must act on it, show it inline or in a dialog.
• Offer at most one action in a toast, such as Undo or View, and give that toast at least 10 seconds (duration: 10000) so the user can read it and reach the button. Toasts pause while the pointer is over them.

<>
  <Button variant="outline" onClick={() => toast("Filter saved")}>
    Default
  </Button>
  <Button
    variant="outline"
    onClick={() => toast.success("Alert assigned to Marina Santos")}
  >
    Success
  </Button>
  <Button
    variant="outline"
    onClick={() => toast.info("Scan queued behind 2 other scans")}
  >
    Info
  </Button>
  <Button
    variant="outline"
    onClick={() => toast.warning("API key expires in 3 days")}
  >
    Warning
  </Button>
  <Button
    variant="outline"
    onClick={() => toast.error("Could not reach the SIEM connector")}
  >
    Error
  </Button>
</>

Long-running work

Scans, exports and imports can take minutes. Never hold the user in a modal or a page-wide spinner for them.

1. Start the work and confirm it at once: toast("Export started").
2. Show the progress where the result will appear: a “Running” status on the row, a Progress bar in the card.
3. When it finishes, say so with an action that leads to the result: “Export ready” with Download, “Scan finished” with View results.
4. When it fails, toast.error() with what to do, and keep the failed state visible where the result would have been, so the user finds it after the toast is gone.

Inline messages

Use an Alert for a message with a title and details, and an Info Banner for a single line. Place it at the top of the area it describes, not at the top of the page when only one card is affected. An inline message stays until the condition behind it is gone; do not make the user dismiss information that is still true.

<div className="grid w-full max-w-md gap-3">
  <InfoBanner>Results include 2 of 3 tenants you can access.</InfoBanner>
  <InfoBanner tone="success">
    All connectors reported in the last hour.
  </InfoBanner>
  <InfoBanner tone="warning">
    The CrowdStrike sync is delayed. Data may be 20 minutes old.
  </InfoBanner>
  <InfoBanner tone="neutral">
    This report is a snapshot from October 1 and does not update.
  </InfoBanner>
  <InfoBanner tone="destructive">
    Exports are disabled until the storage quota is raised.
  </InfoBanner>
</div>

Confirmations

Ask for confirmation only before an action that destroys data, cannot be undone or affects other people. Asking before routine actions teaches users to confirm without reading.

• The title asks the question and names the object: “Delete asset vpn-01?”
• The body says what else changes and whether it can be undone.
• The confirm button repeats the verb (“Delete asset”) with the destructive variant; the other button is Cancel.
• For the most destructive actions on a named resource, such as deleting a tenant, ask the user to type its name.

function ConfirmDialogDestructive() {
  const [result, setResult] = React.useState<boolean | null>(null)

  async function deleteReport() {
    const confirmed = await confirm({
      title: "Delete this report?",
      description:
        "Monthly exposure report, September 2026 will be deleted for everyone in the tenant. This cannot be undone.",
      confirmLabel: "Delete report",
      confirmVariant: "destructive",
    })
    setResult(confirmed)
  }

  return (
    <div className="flex flex-col items-center gap-3">
      <Button variant="destructive" onClick={deleteReport}>
        Delete report
      </Button>
      <p className="text-sm text-text-secondary">
        {result === null
          ? "Not asked yet."
          : `confirm() resolved to ${result}.`}
      </p>
    </div>
  )
}

Several items

When an action runs on many selected items, report the result once:

Keep the items selected afterwards, so the user can act on what failed.

Writing the message

The words matter as much as the component. Follow Writing: what happened, why when it helps, what to do; no blame; no raw error messages; no “successfully”.