Skip to content
Shaken UI
Sign in

Alert

Save

An 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 alert

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add alert --dry-run

Usage

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

PropTypeDefaultDescription
tone"neutral" | "info" | "success" | "warning" | "danger""neutral"Status hue of the full hairline border, the soft tint, and the glyph. Neutral has no tint.
iconReactNode—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.
dismissLabelstring"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.tsxShow
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>
  );
}