Skip to main content

Alert

Tells the user what just happened, or what is about to.

import { Alert } from "@/fragments/ui";Source

Preview

import { Alert } from '@/components/Alert';

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

Installation

npx @usefragments/cli add alert

Writes src/fragments/ui/components/Alert plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Alert is a compound: import the root and reach its parts through 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 '@/components/Alert';

<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

Success

Confirms the thing the user just did actually landed.

import { Alert } from '@/components/Alert';

<Alert tone="success">
  <Alert.Icon />
  <Alert.Body>
    <Alert.Title>Payment processed</Alert.Title>

Warning

Nothing is broken yet — act before it is.

import { Alert } from '@/components/Alert';

<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 '@/components/Alert';

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

With Action

One button, one job — more than one stalls the reader.

import { Alert } from '@/components/Alert';

<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 '@/components/Alert';

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

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setAlert content - use Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Close sub-components
toneenuminfosuccesswarningdangerinfoTone; controls colour, icon and live-region role
emphasisenumtintsurfacetintHow much surface the tone claims. `tint` washes the card in the tone colour; `surface` keeps the page background and colours only the hairline and title.

Accessibility

  • role="alert" means assistive tech announces it on arrival
  • Alert.Close needs its own label
  • Icon plus wording carry the tone — never color alone

Standards

Guidance

Use when

  • Reporting the outcome of something the user did
  • Flagging a risk before the user hits it
  • Standing status that must stay on screen

Avoid when

  • A one-word status (use Badge)
  • A message that should fade away (use Toast)
  • An invalid field (use the Input error prop)
  • A decision the user must make first (use Dialog)

Related

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

Next steps