Alert

Overview

The Alert component provides a flexible UI element for displaying alert messages. It is composed of several subcomponents such as Alert.Root, Alert.Title, Alert.Description, and Alert.Link to offer a structured and customizable interface.

Installation

import { Alert } from '@harnessio/ui/components'

//...

return (
  <Alert.Root
    theme="info"
    expandable
    dismissible
  >
    <Alert.Title>My Alert</Alert.Title>

    <Alert.Description>This is the description of the alert</Alert.Description>

    <Alert.Link to="/someplace">
      Learn more
    </Alert.Link>
  </Alert.Root>
)

Usage

Anatomy

All parts of the Alert can be imported and composed as required:

<Alert.Root>
  <Alert.Title />
  <Alert.Description />
  <Alert.Link />
</Alert.Root>

• Root — the container. Its theme (info default, success, warning, danger) sets the color and the leading status icon automatically. Add dismissible for a close button, or expandable to collapse long content behind a “Show more” toggle.
• Title (optional) — a short heading for the alert.
• Description — the alert’s message; the main body text.
• Link (optional) — a single action link, rendered with a trailing icon, for a follow-up like “Learn more”.

The status icon is chosen from the theme (info, success, warning, danger) — you don’t pass it yourself.

Best practices

Do

• Use Alert for a message tied to the surrounding content or a recent action — inline, in place, and staying until it’s resolved or dismissed.
• Match the theme to the message: danger for errors and blocked actions, warning for risks, success for confirmations, info for neutral context.
• Lead with the outcome and, when there’s a fix, point to it — a clear Alert.Description and, if useful, one Alert.Link to the next step.
• Use expandable for long messages (like policy text or stack traces) so the alert doesn’t dominate the layout, and dismissible for advisories people can safely clear.

Don’t

• Don’t use Alert for transient, auto-dismissing feedback — use a toast — or for a feed of past notifications, where Alert Item fits better.
• Don’t stack several alerts competing for attention; consolidate or prioritize the most important one.
• Don’t rely on the theme color alone to carry meaning — the text should state the situation clearly.
• Don’t make an error alert dismissible if the underlying problem still blocks the user.

Content

• Write the Description in plain language: what happened, why it matters, and what to do next.
• Keep the Title short and specific when you use one; it’s optional and often the description alone is enough.
• Use sentence case throughout, and give any Alert.Link a verb-led label (“Learn more”, “View repository”).
• For long technical detail (URLs, tokens, policy text), rely on expandable rather than trimming information people may need to copy.

Accessibility

Alert.Root renders with role="alert", so assistive tech announces it as soon as it appears — this makes it well suited to conveying important, time-sensitive messages.

Keyboard

• The alert body itself isn’t focusable; its interactive parts are.
• The Alert.Link, the dismissible close button, and the expandable “Show more” toggle are each native controls in the tab order, activated with Enter (and Space for the buttons).

Labeling

• The close button carries a translated aria-label (“Close alert”) and the expandable toggle uses aria-expanded to expose its open/closed state.
• The content sits in a labeled region (role="region", “Alert content”), and the leading status icon is decorative — meaning comes from the text, so state the situation in the Description.

Focus & states

• The link, close, and expand controls each show the standard focus ring (:focus-visible) via the --cn-focus token.
• Dismissing an alert removes it from the DOM entirely; expanding/collapsing toggles a fade overlay over the clipped content.

Known limitations

• role="alert" announces on mount, not on update. An alert rendered on page load may be announced immediately or missed, depending on timing; for a message that must be heard, render the alert in response to the action rather than having it already present.
• Focus isn’t moved to the alert. When an alert appears after an action, focus stays where it was; if the alert blocks progress, move focus to it (or its first control) yourself.
• Dismissing doesn’t manage focus. After the close button removes the alert, focus is not returned to a sensible neighbor, so keyboard users can lose their place.

Properties

Properties

Root

The Root component serves as the main container for all alert elements.

Prop	Required	Default	Type
children	true		ReactNode
className	false		string
theme	false	'info'	'info' | 'success' | 'warning' | 'danger'
dismissible	false		boolean
expandable	false		boolean
onDismiss	false		() => void

Title

The Title component displays the title of the alert.

<Alert.Title>Alert Title</Alert.Title>

Prop	Required	Default	Type
children	true		ReactNode
className	false		string

Description

The Description component displays the description of the alert.

<Alert.Description>This is the alert description.</Alert.Description>

Prop	Required	Default	Type
children	true		ReactNode
className	false		string

Link

The Link component is used to create a link within the alert.

<Alert.Link to="/path">Learn more</Alert.Link>

Prop	Required	Default	Type
to	true		string
children	true		ReactNode
className	false		string
external	false	false	boolean
asChild	false	false	boolean