Alert
Alerts communicate persistent inline feedback with a clear semantic tone, concise text, and accessible announcement options when content changes dynamically.
Overview and decision boundary
Use Alert for inline feedback that stays in the page flow until the content changes or the consumer dismisses it.
Do not use Alert as a toast replacement or dismiss required information without a durable alternative.
import { Info, X } from "@nerio-ui/adapters/icons";import { Alert } from "@nerio-ui/ui";import { Button } from "@nerio-ui/ui/client";<Alert icon={Info} title="Update available" action={<Button size="sm">Refresh</Button>} closeAction={ <Button aria-label="Close alert" icon={X} size="sm" tooltip={false} variant="secondary" /> }> A new version of the application is available. Refresh to get the latest features and fixes.</Alert>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add alertimport { Circle } from '@nerio-ui/adapters/icons';import { Alert } from '@nerio-ui/ui';Usage
import { Circle } from '@nerio-ui/adapters/icons';import { Alert } from '@nerio-ui/ui';<Alert tone="info" title="Invite sent" icon={Circle}>Collaborators will receive an email shortly.</Alert>Variants
| Tone | Use |
|---|---|
neutral | Low-emphasis status or message that does not need a semantic emphasis. |
info | Informational context that should remain calm and visible in the page flow. |
success | Positive completion or validation feedback. |
warning | An issue that needs attention without blocking the entire flow. |
danger | An error, destructive outcome, or blocking state. |
Anatomy
| Slot | Purpose |
|---|---|
root | Inline feedback region that applies tone and spacing tokens. |
icon | Optional decorative icon rendered through the Nerio icon adapter. |
content | Container for the title and descriptive content. |
title | Optional short summary that establishes the message hierarchy. |
description | Body content that explains the state or provides a next step. |
action | Optional actions rendered below the description. |
close | Optional consumer-owned icon button that dismisses the alert. |
States
| State | Behavior |
|---|---|
Static | No live-region semantics are applied by default. |
Status update | Use role="status" for a dynamic, non-urgent update. |
Urgent update | Use role="alert" only when a dynamic error needs immediate announcement. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Static inline alerts do not announce by default; pass role="status" or role="alert" only for dynamic updates that need announcement.
- Tone is supported by text; do not rely on color alone.
- Optional icons must pass through the Nerio icon adapter.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Values | Purpose |
|---|---|---|
tone | neutral | info | success | warning | danger | Selects the semantic feedback treatment. |
title | ReactNode | Adds a concise summary above the description. |
icon | IconComponent | Renders a decorative icon through the Nerio icon adapter. |
action | ReactNode | Adds one or more actions below the description. |
closeAction | ReactNode | Adds a consumer-owned close control in the trailing slot. |
role | status | alert | Opt into announcement semantics only for dynamic content. |
children | ReactNode | Provides the descriptive message content. |
className | string | Extends the root without replacing component tokens. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | alert installs five source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | None. |
Package dependencies | clsx, react |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Alert is a flat muted surface: semantic color stays on the icon while title and description remain neutral.
- Use the message text and optional icon together so status never depends on color alone.
Do / do not
Do
Use Alert for inline validation summaries, persistent notices, and contextual feedback. Keep actions below the description.
Do not
Use Alert as a toast replacement or make required information disappear without a durable alternative.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Layout | --n-alert-gap / --n-alert-padding / --n-alert-radius | Controls compact spacing and shape. |
Surface | --n-alert-border-width / --n-alert-border / --n-alert-background / --n-alert-shadow | Keeps persistent feedback flat, muted, and borderless by default. |
Emphasis | --n-alert-title-color / --n-alert-icon-color | Keeps the title neutral and applies semantic emphasis only to the icon. |
Icon | --n-alert-icon-size | Controls the optional icon scale. |
Semantic tones | --n-color-status-info / success / warning / danger | Controls semantic icon emphasis without changing the neutral text hierarchy. |