React Alert component

Preview

import { Alert } from '@usefragments/ui';

<Alert tone="info">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Content>

Usage

Use when

Flagging a risk before the user hits it
A failure the user must fix, said where it happened
Standing information that must stay on screen

Avoid when

A one-word status or a pass verdict (use Badge)
A confirmation that should fade away (use Toast)
An invalid field (use the Input error prop)
A decision the user must make first (use Dialog)
A neutral note with no state (use Text or Box)

Implementation notes

Match tone to real stakes; an error that is not an error trains people to ignore you
There is no success tone: a pass goes to a Badge verdict and a confirmation to Toast
Every danger alert says what to do next
Add Alert.Title only when the message needs two lines
At most two actions; Alert.Action is a small soft Button and they wrap under the copy
Only dismissible when losing the message costs nothing; use open and onOpenChange to bring it back
Alert.Action and Alert.Close default to type="button", so they are safe inside a form
Alert.Close runs your onClick and still respects preventDefault()

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import Alert once, then compose its parts with dot notation.

Alert.Icon
Alert.Body
Alert.Title
Alert.Content
Alert.Actions
Alert.Action
Alert.Close

Neutral context — nothing went wrong, nothing needs doing.

import { Alert } from '@usefragments/ui';

<Alert tone="info">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Content>
      Your session will expire in 15 minutes. Save your work to avoid losing changes.
    </Alert.Content>
  </Alert.Body>
</Alert>

Examples

Warning

Nothing is broken yet — act before it is.

import { Alert } from '@usefragments/ui';

<Alert tone="warning">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Title>Storage almost full</Alert.Title>

Error

Something failed; say what to do about it.

import { Alert } from '@usefragments/ui';

<Alert tone="danger">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Title>Upload failed</Alert.Title>

With Action

One small soft button; a second verb wraps beside it, never more.

import { Alert } from '@usefragments/ui';

<Alert tone="warning">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Title>Update available</Alert.Title>

Dismissible

A close button suits news the user can safely ignore.

import { Alert } from '@usefragments/ui';

<Alert tone="info">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Content>

Controlled

open and onOpenChange let the page bring a dismissed alert back.

import { Alert } from '@usefragments/ui';

const [open, setOpen] = React.useState(true);

<Alert tone="info" open={open} onOpenChange={setOpen}>
  <Alert.Icon />

API reference

Component props
Prop	Type	Default	Description
`Action.children`	`React.ReactNode`	Not set	The label. Optional only so a Button can be the `render` element of a trigger (`<Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>`), where the trigger's children become the label.
`Action.focusableWhenDisabled`	`boolean \| undefined`	Not set	Keep a disabled button in the tab order (`aria-disabled` instead of `disabled`), so keyboard and screen reader users can still reach it and read why it is unavailable.
`Action.fullWidth`	`boolean \| undefined`	Not set	Fill the parent's width. Without it a button is as wide as its label in every parent, a column stack or a grid cell included.
`Action.nativeButton`	`boolean \| undefined`	Not set	Whether the rendered element is a native `<button>`. Inferred from an element passed to `render` (a `<button>`, or a component without `href`); pass it when `render` is a function or a component that renders an anchor without an `href` prop.
`Action.pending`	`boolean \| undefined`	Not set	Work started by this button is running. The button sets `aria-busy` and ignores further presses at once; after a second (`--fui-pending-delay`) its label fades and a spinner takes its place, and its width holds.
`Action.render`	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Not set	Replace the rendered element, e.g. `render={<a href="/docs" />}` or a router link. A rendered anchor keeps its link semantics (no button role); the button's look, pending and disabled behaviour move onto it.
`Actions.children`Required	`React.ReactNode`	Not set	—
`Body.children`Required	`React.ReactNode`	Not set	—
`children`Required	`React.ReactNode`	Not set	Alert content - use Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Close sub-components
`Close.children`	`React.ReactNode`	Not set	A replacement glyph. Defaults to a cross.
`Close.defaultPressed`	`boolean \| undefined`	Not set	Initial pressed state of an uncontrolled toggle.
`Close.nativeButton`	`boolean \| undefined`	Not set	Whether the rendered element is a native `<button>`. Inferred from an element passed to `render` (a `<button>`, or a component without `href`).
`Close.onPressedChange`	`((pressed: boolean) => void) \| undefined`	Not set	Called with the next pressed state when the toggle is pressed.
`Close.pending`	`boolean \| undefined`	Not set	Work started by this button is running: `aria-busy`, presses ignored, and after a second the icon gives way to a spinner.
`Close.pressed`	`boolean \| undefined`	Not set	Controlled pressed state. Passing `pressed`, `defaultPressed` or `onPressedChange` makes the button a toggle: it sets `aria-pressed` and paints the selection wash and ring while pressed.
`Close.render`	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Not set	Replace the rendered element, e.g. `render={<a href="/settings" />}` or a router link. A rendered anchor keeps its link semantics (no button role); the look, pending and disabled behaviour move onto it.
`Close.value`	`string \| undefined`	Not set	Form value of the button, or the toggle's value inside a group.
`Content.children`Required	`React.ReactNode`	Not set	—
`Icon.children`	`React.ReactNode`	Not set	A replacement glyph. Defaults to the tone's icon.
`onOpenChange`	`((open: boolean) => void) \| undefined`	Not set	Called with false when Alert.Close is pressed
`open`	`boolean \| undefined`	Not set	Controlled visibility. Leave unset and the alert hides itself once Alert.Close is pressed.
`Title.children`Required	`React.ReactNode`	Not set	—
`tone`	`AlertTone \| undefinedinfowarningdanger`	`info`	Tone; sets the tint fill, the icon, the title ink and the live-region role

Accessibility

role="alert" (warning, danger) means assistive tech announces it on arrival; info uses role="status"
aria-labelledby and aria-describedby point only at a Title and Content that render
Alert.Close is labelled "Dismiss alert" unless you pass your own aria-label
Icon plus wording carry the tone, never colour alone

Standards references

BadgealternativeUse Badge for compact, inline status labels
ToastalternativeUse Toast for transient notifications that auto-dismiss
DialogsiblingUse Dialog for blocking confirmations

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.