Components
Alert
Persistent inline messages for information, success, warning, and error states.
Alert shows a persistent message inside the page, such as a form-level error, an account warning,
or a status note. Use it when the message should stay visible until the user resolves it. For brief,
non-blocking feedback use Toast; for decisions that block the workflow
use AlertDialog.
Import the components from @orkest/ui/client.
Variants#
New version available
Orkest UI 0.2 adds updated theme tokens.
Changes saved
Your profile is up to date.
Unsaved changes
Leaving this page will discard your draft.
Upload failed
Check your connection and try again.
import { Stack } from '@orkest/ui';
import {
Alert,
AlertDescription,
AlertTitle,
} from '@orkest/ui/client';
export function Example() {
return (
<Stack gap={3}>
<Alert variant="info">
<AlertTitle>New version available</AlertTitle>
<AlertDescription>
Orkest UI 0.2 adds updated theme tokens.
</AlertDescription>
</Alert>
<Alert variant="success">
<AlertTitle>Changes saved</AlertTitle>
<AlertDescription>Your profile is up to date.</AlertDescription>
</Alert>
<Alert variant="warning">
<AlertTitle>Unsaved changes</AlertTitle>
<AlertDescription>
Leaving this page will discard your draft.
</AlertDescription>
</Alert>
<Alert variant="error">
<AlertTitle>Upload failed</AlertTitle>
<AlertDescription>
Check your connection and try again.
</AlertDescription>
</Alert>
</Stack>
);
}The icon shape and the text carry the state. The tinted surface reinforces it but is not the only signal. Both themes use semantic tokens, so no component-level theme overrides are required.
Anatomy#
Alertis the container. It ownsvariant, the optional icon, the close button, and the live region role.AlertIconis rendered automatically and derives its glyph and color from the variant. Override the glyph withicon, or remove it withicon={null}.AlertTitleandAlertDescriptionrender paragraphs. Both are optional and may be used alone.AlertActionis an optional action slot for one or two buttons or links.AlertCloseis rendered automatically whenclosableis set. It is also exported for custom containers.
Optional title and icon#
A description alone can be enough for short statuses. Use icon={null} when the message does not
need a status glyph.
Two-factor authentication is enabled for this account.
Maintenance window
Expect brief interruptions on Saturday, 02:00–04:00 UTC.
import { Stack } from '@orkest/ui';
import {
Alert,
AlertDescription,
AlertTitle,
} from '@orkest/ui/client';
export function Example() {
return (
<Stack gap={3}>
<Alert variant="info">
<AlertDescription>
Two-factor authentication is enabled for this account.
</AlertDescription>
</Alert>
<Alert variant="warning" icon={null}>
<AlertTitle>Maintenance window</AlertTitle>
<AlertDescription>
Expect brief interruptions on Saturday, 02:00–04:00 UTC.
</AlertDescription>
</Alert>
</Stack>
);
}When the title is omitted, the description uses the primary foreground color instead of the muted one.
Custom icon#
Pass a Lucide icon to icon when a more specific glyph communicates the message better. The color
still follows the variant.
Early access
This workspace is enrolled in the preview program.
import {
Alert,
AlertDescription,
AlertTitle,
} from '@orkest/ui/client';
import { Rocket } from 'lucide-react';
export function Example() {
return (
<Alert variant="info" icon={Rocket}>
<AlertTitle>Early access</AlertTitle>
<AlertDescription>
This workspace is enrolled in the preview program.
</AlertDescription>
</Alert>
);
}Closable#
Alert is controlled: closable renders the close button and onClose reports the request, but the
alert does not remove itself. Hide it in the parent so the same state can be restored or persisted.
Verify your email
Some features stay limited until the address is confirmed.
import { useState } from 'react';
import { Button } from '@orkest/ui';
import {
Alert,
AlertDescription,
AlertTitle,
} from '@orkest/ui/client';
export function Example() {
const [visible, setVisible] = useState(true);
if (!visible) {
return (
<Button variant="outline" onClick={() => setVisible(true)}>
Show alert again
</Button>
);
}
return (
<Alert variant="warning" closable onClose={() => setVisible(false)}>
<AlertTitle>Verify your email</AlertTitle>
<AlertDescription>
Some features stay limited until the address is confirmed.
</AlertDescription>
</Alert>
);
}Actions#
AlertAction sits below the text and can hold buttons or links. Keep actions directly related to
the message; do not turn the alert into a form.
Could not load billing data
The payment provider did not respond in time.
import { Button } from '@orkest/ui';
import {
Alert,
AlertAction,
AlertDescription,
AlertTitle,
} from '@orkest/ui/client';
export function Example() {
return (
<Alert variant="error">
<AlertTitle>Could not load billing data</AlertTitle>
<AlertDescription>
The payment provider did not respond in time.
</AlertDescription>
<AlertAction>
<Button size="sm" variant="outline">
Retry
</Button>
<Button size="sm" variant="ghost">
Contact support
</Button>
</AlertAction>
</Alert>
);
}Accessibility#
erroralerts default torole="alert". Other variants default torole="status"so ordinary information does not interrupt the screen reader.- Pass
roleto match the scenario, orrole={null}for a static container that should never be announced. Avoidrole="alert"for messages that are already visible on page load. - The close button uses the accessible name
Dismiss. Override it withcloseLabelwhen several alerts share the page. - The status icon is decorative by default because the title and description carry the state. Pass
labeltoAlertIconwhen you need a meaningful standalone icon. AlertTitlerenders a paragraph, not a heading, so repeated alerts do not pollute the document outline. Use the surrounding page structure for headings.- State is conveyed by text and icon shape, not by color alone.
- Focus is visible on the close button and action controls.
- The close-button hover transition respects
prefers-reduced-motion.
Props#
Alert#
| Prop | Type | Default |
|---|---|---|
variant | 'info' | 'success' | 'warning' | 'error' | 'info' |
| Visual treatment, default icon, and default live region role. | ||
icon | LucideIcon | null | Variant icon |
| Replaces the status icon. Pass `null` to render no icon. | ||
closable | boolean | false |
| Renders a close button that calls `onClose`. | ||
onClose | () => void | — |
| Called when the close button is clicked. The parent owns visibility. | ||
closeLabel | string | 'Dismiss' |
| Accessible name of the close button. | ||
role | AriaRole | null | 'alert' for error, 'status' otherwise |
| Overrides the live region role. Pass `null` to remove it. | ||
native attributes | HTMLAttributes<HTMLDivElement> | — |
| ARIA attributes, event handlers, className, style, and ref are forwarded. | ||
AlertIcon#
| Prop | Type | Default |
|---|---|---|
variant | 'info' | 'success' | 'warning' | 'error' | — |
| Overrides the variant inherited from the surrounding `Alert`. | ||
icon | LucideIcon | — |
| Overrides the default glyph for the variant. | ||
label | string | — |
| Accessible name for the icon. Without it the icon is decorative and hidden from assistive technology. | ||
AlertTitle, AlertDescription, AlertAction, and AlertClose#
| Prop | Type | Default |
|---|---|---|
AlertTitle | HTMLAttributes<HTMLParagraphElement> | — |
| Primary message. Renders a paragraph. | ||
AlertDescription | HTMLAttributes<HTMLParagraphElement> | — |
| Supporting message. Renders a paragraph. | ||
AlertAction | HTMLAttributes<HTMLDivElement> | — |
| Action slot rendered below the text. Accepts buttons, links, or other controls. | ||
AlertClose.label | string | 'Dismiss' |
| Accessible name of the icon-only close button. | ||
Related#
- Toast for temporary feedback that does not need to stay on the page.
- AlertDialog for decisions that require confirmation.
- Badge for compact status labels.