Alert

When to use

• A warning or notice about the page or account: “Your trial ends in 3 days”
• A summary of form errors at the top of a form
• The result of an action that must stay visible until it is dealt with

Not for a brief confirmation that can go away by itself — use a Toast.

Choosing between messages and popups:

Component	Use it for	For example
Dialog	Something that needs a decision or input before the user carries on; the page is blocked meanwhile	Confirm a delete, edit a record in a form
Drawer	A panel that slides in from an edge and blocks the page; the first choice on a phone	Share options, a mobile nav, a filter panel
Popover	Extra content or controls next to a button, while the rest of the page stays usable	Filter panel, share options, details card
Menu	A list of actions or settings opened from a button	“More actions ⋯”, a View menu
Tooltip	A short text label on hover or focus; nothing in it can be clicked	Name of an icon button, a keyboard shortcut
HoverCard	A preview of where a link goes, on hover or focus; nothing essential in it	A profile behind an @mention, a repository’s summary
Toast	A brief confirmation after an action, which goes away by itself	“Saved”, “Archived — Undo”
Alert	A message that stays in the page until the situation changes	“Your trial ends in 3 days”, a form error summary

Scheduled maintenance

Sunday 02:00–03:00 UTC.

New in 4.16

Field, Link and Slider landed.

Saved

Your changes are live.

Storage almost full

You have used 92% of your plan.

Payment failed

Check the card details and try again.

import { Alert } from '@arun-dev/ui';

const icon = (
  <svg
    viewBox="0 0 16 16"
    width="16"
    height="16"
    fill="none"
    stroke="currentColor"
    strokeWidth="1.5"
  >
    <circle cx="8" cy="8" r="6.5" />
    <path d="M8 7v4M8 5h.01" strokeLinecap="round" />
  </svg>
);

const tones = [
  { tone: 'neutral', title: 'Scheduled maintenance', text: 'Sunday 02:00–03:00 UTC.' },
  { tone: 'info', title: 'New in 4.16', text: 'Field, Link and Slider landed.' },
  { tone: 'success', title: 'Saved', text: 'Your changes are live.' },
  { tone: 'warning', title: 'Storage almost full', text: 'You have used 92% of your plan.' },
  { tone: 'error', title: 'Payment failed', text: 'Check the card details and try again.' },
] as const;

export default function AlertTones() {
  return (
    <div
      style={{
        display: 'grid',
        gap: 'var(--space-sm)',
        inlineSize: '28rem',
        maxInlineSize: '100%',
      }}
    >
      {tones.map(({ tone, title, text }) => (
        <Alert.Root key={tone} tone={tone} icon={icon}>
          <Alert.Title>{title}</Alert.Title>
          <Alert.Description>{text}</Alert.Description>
        </Alert.Root>
      ))}
    </div>
  );
}

Alert is a message box with a tone, an optional icon, a title and a description.

Announcing it

An alert that is on the page from the start is just content, so it has no live role by default. When it appears in response to something, add one so screen readers read it out:

• role="alert": urgent, read out at once. A failed save, a lost connection.
• role="status": polite, read out when the user is idle. “Saved”, “3 results”.

{
  error && (
    <Alert.Root tone="error" role="alert">
      <Alert.Title>Save failed</Alert.Title>
    </Alert.Root>
  );
}

For a brief message that goes away on its own, use a Toast.

Props

Alert.Root

Alert.Root props

Prop	Type	Default	Description
tone	'neutral' | 'info' | 'success' | 'warning' | 'error'	'neutral'	Colour, on the status tokens.
icon	ReactNode	—	An icon before the text. Decorative: hidden from assistive technology.
className	string	—	Concatenated with the component's own classes, never replacing them.
render	ReactElement	—	Element or component to render instead of the default. Props, className, event handlers and ref are merged onto it.
ref	Ref<HTMLElement>	—	Ref to the rendered element. Merged with any ref on the render element.
…rest	HTMLAttributes	—	Anything else is spread onto the rendered element, so id, aria-*, data-* and event handlers all reach the DOM.

Alert.Title renders a <p> (pass render={<h2 />} if it heads a section), and Alert.Description a <div>.

Notes

• Tones map onto the --color-status-* tokens, as Badge’s do. Override --alert-error-bg and the other tone tokens to restyle one tone.