Alert
SaveAn inline callout with neutral, info, success, warning, and danger tones, a status glyph, a title, a description, and optional actions and dismiss.
- Category
- Feedback
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Alert preview
Warning:
Your API key expires in 3 days
Deployments that use
sk_live_4f2a will stop on November 17. Rotate the key and update your environment variables.Error:
Payment failed
The card ending in 4242 was declined. Update your billing details to keep the Team plan.
Success:
Domain verified
docs.acme.dev now serves traffic over HTTPS.
Info:
Scheduled maintenance on Sunday, 02:00 to 03:00 UTC
Builds queue during the window and start automatically afterwards.
Preview deployments are public by default
Turn on password protection in project settings to restrict them.
Installation
npx @shakenui/cli add alertReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add alert --dry-runUsage
alert-example.tsx
"use client";
import { useState } from "react";
import { Alert, AlertAction, AlertActions, AlertDescription, AlertTitle } from "@/components/shaken/ui/alert";
export default function AlertExample() {
const [showNotice, setShowNotice] = useState(true);
return (
<div className="grid w-full max-w-lg gap-3">
<Alert tone="warning">
<AlertTitle>Your API key expires in 3 days</AlertTitle>
<AlertDescription>
Deployments that use <code>sk_live_4f2a</code> will stop on November 17. Rotate the key and update your
environment variables.
</AlertDescription>
<AlertActions>
<AlertAction>Rotate key</AlertAction>
<AlertAction variant="ghost">Remind me tomorrow</AlertAction>
</AlertActions>
</Alert>
<Alert tone="danger">
<AlertTitle>Payment failed</AlertTitle>
<AlertDescription>
The card ending in 4242 was declined. <a href="#billing">Update your billing details</a> to keep the Team plan.
</AlertDescription>
</Alert>
<Alert tone="success">
<AlertTitle>Domain verified</AlertTitle>
<AlertDescription>docs.acme.dev now serves traffic over HTTPS.</AlertDescription>
</Alert>
{showNotice ? (
<Alert tone="info" onDismiss={() => setShowNotice(false)} dismissLabel="Dismiss maintenance notice">
<AlertTitle>Scheduled maintenance on Sunday, 02:00 to 03:00 UTC</AlertTitle>
<AlertDescription>Builds queue during the window and start automatically afterwards.</AlertDescription>
</Alert>
) : (
<button
type="button"
onClick={() => setShowNotice(true)}
className="justify-self-start rounded-md text-xs text-zinc-500 underline underline-offset-[3px] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500"
>
Show the maintenance notice again
</button>
)}
<Alert>
<AlertTitle>Preview deployments are public by default</AlertTitle>
<AlertDescription>Turn on password protection in project settings to restrict them.</AlertDescription>
</Alert>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| tone | "neutral" | "info" | "success" | "warning" | "danger" | "neutral" | Status hue of the full hairline border, the soft tint, and the glyph. Neutral has no tint. |
| icon | ReactNode | — | Replaces the tone's glyph. Pass null to hide the icon. |
| live | "off" | "polite" | "assertive" | "off" | off is a static callout read in page order; polite renders role="status"; assertive renders role="alert". Use the live modes only for alerts that appear in response to an action. |
| onDismiss | () => void | — | Shows a dismiss button in the top right corner that calls this. Remove the alert in your handler. |
| dismissLabel | string | "Dismiss" | Accessible name of the dismiss button. |
| AlertAction variant | "secondary" | "ghost" | "secondary" | A 28px hairline button or a quieter text button for actions inside AlertActions. |
Accessibility
- Static by default: no live role, so callouts on page load are read in order instead of interrupting.
- live="polite" renders role="status" and live="assertive" renders role="alert" for alerts that appear after an action.
- The tone is spoken as a visually hidden prefix (Warning:, Error:, Success:, Info:), so the meaning does not depend on color or the glyph, which is aria-hidden.
- The tone also reads in shape: a triangle for warning, a check, an x, and an i in a circle.
- The dismiss button is a native button with an accessible name and a visible focus ring; actions are native buttons with focus rings.
- Light-mode text stays zinc-950 and zinc-600 on the 6 to 7 percent tints, which keeps body text above WCAG AA.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/alert.tsxalert- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/alert/0.1.0.json.
ui/alert.tsxShowHide
ui/alert.tsx
import type { ComponentProps, ReactNode } from "react";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
export type AlertTone = "neutral" | "info" | "success" | "warning" | "danger";
// A full hairline in the status hue and a soft tint of the same hue. No side stripe:
// the tone reads from the glyph shape and the title first, color second.
const tones: Record<AlertTone, { box: string; glyph: string; label: string }> = {
neutral: {
box: "border-zinc-950/10 bg-white dark:border-white/12 dark:bg-black",
glyph: "text-zinc-500 dark:text-zinc-400",
label: "Note",
},
info: {
box: "border-sky-500/30 bg-sky-500/[0.06] dark:border-sky-400/25 dark:bg-sky-400/[0.06]",
glyph: "text-sky-600 dark:text-sky-400",
label: "Info",
},
success: {
box: "border-emerald-500/30 bg-emerald-500/[0.06] dark:border-emerald-400/25 dark:bg-emerald-400/[0.06]",
glyph: "text-emerald-600 dark:text-emerald-400",
label: "Success",
},
warning: {
box: "border-amber-500/35 bg-amber-500/[0.07] dark:border-amber-400/25 dark:bg-amber-400/[0.06]",
glyph: "text-amber-600 dark:text-amber-400",
label: "Warning",
},
danger: {
box: "border-red-500/30 bg-red-500/[0.06] dark:border-red-400/25 dark:bg-red-400/[0.06]",
glyph: "text-red-600 dark:text-red-400",
label: "Error",
},
};
export interface AlertProps extends Omit<ComponentProps<"div">, "title"> {
/** Status hue of the border, tint, and glyph. Neutral has no tint. */
tone?: AlertTone;
/** Replaces the tone's glyph. Pass `null` to show no icon. */
icon?: ReactNode;
/**
* How a screen reader hears it. `off` (default) is a static callout read in page order;
* `polite` makes it a status region; `assertive` makes it an alert that interrupts.
* Use the live modes only for alerts that appear in response to something.
*/
live?: "off" | "polite" | "assertive";
/** Shows a dismiss button that calls this. Remove the alert in your handler. */
onDismiss?: () => void;
/** Accessible name of the dismiss button. */
dismissLabel?: string;
}
/**
* An inline callout. Compose it with `AlertTitle`, `AlertDescription`, and `AlertActions`.
*
* ```tsx
* <Alert tone="warning">
* <AlertTitle>Your API key expires in 3 days</AlertTitle>
* <AlertDescription>Rotate it to keep deployments running.</AlertDescription>
* </Alert>
* ```
*/
export function Alert({
tone = "neutral",
icon,
live = "off",
onDismiss,
dismissLabel = "Dismiss",
className,
children,
...props
}: AlertProps) {
const config = tones[tone];
const glyph = icon === undefined ? <AlertGlyph tone={tone} /> : icon;
return (
<div
role={live === "assertive" ? "alert" : live === "polite" ? "status" : undefined}
data-tone={tone}
className={cx(
"relative flex w-full items-start gap-3 rounded-xl border px-4 py-3.5 text-sm leading-5 text-zinc-950 dark:text-white",
"transition-[background-color,border-color] duration-200 ease-out motion-reduce:transition-none",
config.box,
onDismiss && "pr-11",
className,
)}
{...props}
>
{glyph ? (
<span
aria-hidden="true"
className={cx("mt-0.5 flex size-4 shrink-0 items-center justify-center [&_svg]:size-4", config.glyph)}
>
{glyph}
</span>
) : null}
{/* The tone is also spoken, so the meaning does not depend on the color or glyph. */}
{tone !== "neutral" ? <span className="sr-only">{config.label}: </span> : null}
<div className="grid min-w-0 flex-1 gap-1">{children}</div>
{onDismiss ? (
<button
type="button"
aria-label={dismissLabel}
onClick={onDismiss}
className={cx(
"absolute top-2.5 right-2.5 inline-flex size-7 items-center justify-center rounded-md text-zinc-500",
"transition-colors duration-150 ease-out motion-reduce:transition-none",
"hover:bg-zinc-950/[0.05] hover:text-zinc-950 dark:text-zinc-400 dark:hover:bg-white/[0.08] dark:hover:text-white",
"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500",
)}
>
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none" className="size-3.5">
<path d="M4.5 4.5l7 7M11.5 4.5l-7 7" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
</button>
) : null}
</div>
);
}
/** The alert's one-line summary. Renders a `<p>`; it is not a heading, so it never breaks the page outline. */
export function AlertTitle({ className, ...props }: ComponentProps<"p">) {
return <p className={cx("font-medium text-pretty text-zinc-950 dark:text-white", className)} {...props} />;
}
/** Supporting text under the title. Renders a `<div>` so it can hold paragraphs, lists, or links. */
export function AlertDescription({ className, ...props }: ComponentProps<"div">) {
return (
<div
className={cx(
"text-pretty text-zinc-600 dark:text-zinc-400",
"[&_a]:font-medium [&_a]:text-zinc-950 [&_a]:underline [&_a]:decoration-zinc-950/25 [&_a]:underline-offset-[3px] [&_a:hover]:decoration-zinc-950/60",
"dark:[&_a]:text-white dark:[&_a]:decoration-white/30 dark:[&_a:hover]:decoration-white/70",
"[&_code]:font-mono [&_code]:text-[0.92em] [&_code]:text-zinc-950 dark:[&_code]:text-white",
className,
)}
{...props}
/>
);
}
/** A row of actions under the text. Holds `AlertAction` buttons or your own `Button`s. */
export function AlertActions({ className, ...props }: ComponentProps<"div">) {
return <div className={cx("mt-2 flex flex-wrap items-center gap-2", className)} {...props} />;
}
export interface AlertActionProps extends ComponentProps<"button"> {
/** `secondary` draws a hairline button; `ghost` is text only, for a quieter second action. */
variant?: "secondary" | "ghost";
}
/** A compact 28px action sized for the alert. `type` defaults to `button`. */
export function AlertAction({ variant = "secondary", type = "button", className, ...props }: AlertActionProps) {
return (
<button
type={type}
className={cx(
"inline-flex h-7 items-center gap-1.5 rounded-lg px-2.5 text-xs font-medium whitespace-nowrap select-none",
"transition-[background-color,border-color,color,scale] duration-150 ease-out active:duration-100 motion-reduce:transition-none",
"motion-safe:active:scale-[0.97]",
"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
"disabled:pointer-events-none disabled:opacity-45",
variant === "secondary"
? cx(
"border border-zinc-950/12 bg-white text-zinc-950 hover:border-zinc-950/20 hover:bg-zinc-50",
"dark:border-white/15 dark:bg-black dark:text-white dark:hover:border-white/25 dark:hover:bg-white/[0.06]",
)
: "text-zinc-600 hover:bg-zinc-950/[0.05] hover:text-zinc-950 dark:text-zinc-400 dark:hover:bg-white/[0.07] dark:hover:text-white",
className,
)}
{...props}
/>
);
}
/** The tone's default 16px glyph: the same circle shapes the toasts and status glyphs use. */
export function AlertGlyph({ tone }: { tone: AlertTone }) {
const stroke = { stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" } as const;
return (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
{tone === "warning" ? (
<>
<path d="M7.13 2.5a1 1 0 0 1 1.74 0l5.2 9.1a1 1 0 0 1-.87 1.5H2.8a1 1 0 0 1-.87-1.5Z" {...stroke} />
<path d="M8 6.25v2.75" {...stroke} />
<circle cx="8" cy="11" r="0.75" fill="currentColor" />
</>
) : (
<>
<circle cx="8" cy="8" r="6.25" {...stroke} />
{tone === "success" ? (
<path d="m5.5 8.25 1.75 1.75 3.25-3.75" {...stroke} />
) : tone === "danger" ? (
<path d="m6 6 4 4m0-4-4 4" {...stroke} />
) : (
<>
<path d="M8 7.5v3.25" {...stroke} />
<circle cx="8" cy="5.25" r="0.75" fill="currentColor" />
</>
)}
</>
)}
</svg>
);
}