oks-ui

How to Use

Alert

Alert displays contextual feedback messages that inform users about the result of an action or a system state. It supports three visual variants (solid, soft, bordered), seven color roles (default, primary, secondary, info, success, warning, danger), and dismissible behavior via the isClosable prop. Each alert has a title, a description, and an optional icon. The alert's icon automatically matches the color role, but can be overridden with a custom icon or hidden entirely. Alerts are non-modal and do not block user interaction — use them inline within forms, at the top of pages, or inside cards.

import {Alert} from "oks-ui"

Feedback After an Action

The most common use case for Alert is showing feedback after form submission, API calls, or user actions. Show a success alert when an operation completes, a danger alert when it fails, and a warning alert when user intervention is needed. Use conditional rendering (state management) to show and hide the alert. The isClosable prop adds an X button for dismissal, and the onClose callback lets you reset state.

function FeedbackExample() {
  const [status, setStatus] = useState<"success" | "error" | null>(null);

  async function handleSubmit() {
    try {
      await fetch("/api/data", { method: "POST" });
      setStatus("success");
    } catch {
      setStatus("error");
    }
  }

  return (
    <div className="space-y-4">
      {status === "success" && (
        <Alert
          title="Saved!"
          description="Your changes were saved successfully."
          color="success"
          isClosable
          onClose={() => setStatus(null)}
        />
      )}
      {status === "error" && (
        <Alert
          title="Error"
          description="Something went wrong. Please try again."
          color="danger"
          isClosable
          onClose={() => setStatus(null)}
        />
      )}
      <Button onClick={handleSubmit} color="primary">Submit</Button>
    </div>
  );
}

Variants

The variant prop controls the alert's visual density. "solid" (default) renders a filled background with high contrast — use for prominent messages that need attention. "soft" renders a semi-transparent background that blends more naturally into the page — ideal for inline form messages. "bordered" renders with just a colored border and very subtle background — best for subtle, non-intrusive messages in dashboards or cards.

<Alert title="Solid" description="Strong emphasis" color="primary" variant="solid" isClosable={false} />
<Alert title="Soft" description="Moderate emphasis" color="primary" variant="soft" isClosable={false} />
<Alert title="Bordered" description="Subtle emphasis" color="primary" variant="bordered" isClosable={false} />

Color Roles

Each color communicates a specific meaning that users intuitively understand. "success" (green) means an operation completed successfully — use for save confirmations, sent messages, or payment received. "danger" (red) means an error occurred — use for failed operations, validation errors, or critical system issues. "warning" (amber) means caution is needed — use for approaching limits, unsaved changes, or deprecated features. "info" (blue) means general information — use for announcements, tips, or system notifications. Each color automatically sets the alert's icon, border, and background.

<Alert title="Success" description="Payment received" color="success" isClosable={false} />
<Alert title="Error" description="Payment failed" color="danger" isClosable={false} />
<Alert title="Warning" description="Low disk space" color="warning" isClosable={false} />
<Alert title="Info" description="Scheduled maintenance" color="info" isClosable={false} />

Dismissible Behavior

When isClosable is true, a close (X) button appears in the top-right corner. Clicking it calls the onClose callback — use this to hide the alert by setting state. Dismissible alerts are useful for transient feedback like success messages or dismissible notices. For persistent alerts that must be resolved (e.g., a validation error on a form), set isClosable={false} so the user must address the issue before the alert disappears.

function DismissibleDemo() {
  const [visible, setVisible] = useState(true);

  return (
    <div className="space-y-4">
      {visible && (
        <Alert
          title="Dismiss me"
          description="Click the X to close this alert."
          color="primary"
          isClosable
          onClose={() => setVisible(false)}
        />
      )}
      <Button onClick={() => setVisible(true)} variant="soft">
        Show Alert
      </Button>
    </div>
  );
}

Icon Customization

By default, Alert shows an icon that matches its color role. You can override it with a custom icon using the icon prop — pass any ReactNode. To hide the icon entirely, set hideIcon={true}. To hide just the icon's background wrapper (the colored circle behind the icon), set hideIconWrapper={true}. This gives you fine-grained control over the alert's visual density.

<Alert
  title="Custom Icon"
  description="Using a custom icon override"
  color="success"
  icon={<span>🎉</span>}
  isClosable={false}
/>

Accessibility

Alert renders with role="alert" for screen reader announcement. The title and description are connected via aria-labelledby and aria-describedby. When isClosable is true, the close button has built-in aria-label="Close" and responds to both click and keyboard Enter/Space. The alert's color is purely visual — never rely on color alone to convey meaning; the title text should be descriptive enough on its own.

Props Reference

All available props for Alert. See the full API reference page for interactive playground examples.

PropTypeDefaultDescription
titleReactNode—The alert title.
descriptionReactNode—Additional description text.
variant"solid" | "soft" | "bordered""solid"Visual style variant.
color"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger""default"Semantic color role.
isClosablebooleanfalseShow a close button.
iconReactNode—Custom icon override.
hideIconbooleanfalseHide the icon.
hideIconWrapperbooleanfalseHide the icon wrapper.
size"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl""md"Alert size.
onClose() => void—Called when the alert is closed.

Best Practices

  • ◆Keep alert text short and actionable — users should understand what happened and what to do next
  • ◆Use isClosable={false} for inline validation errors on forms so users must fix the issue before the alert disappears
  • ◆Position alerts at the top of forms or modals for maximum visibility; if placed inside a card, anchor it to the top of the card content
  • ◆Use variant="soft" for inline messages within forms — it provides visual distinction without overwhelming the layout
  • ◆Avoid stacking more than 2-3 alerts vertically; consider consolidating multiple errors into a single alert with a list in the description
  • ◆The alert does not trap focus or block interaction — it is non-modal, so users can interact with the rest of the page
  • ◆For toast-style notifications, use the Toast component instead of Alert — Toast slides in from the edge and auto-dismisses
View full API reference for Alert →