Alert

A persistent inline status banner. Use Alert for messages tied to the surrounding UI — a read-only file warning above an inspector, an expired-credentials notice on a settings panel, or an unsaved-changes banner. For transient confirmations like “File saved” or “Export complete”, reach for Toast instead.

Live Preview

When to use

• Alert — persistent inline status that the user reads while they work. Doesn’t auto-dismiss. Sits in the layout.
• Toast — transient confirmation that fades after a few seconds. Sits in an overlay corner. Use useToast.
• Dialog — blocks the rest of the UI and demands a response.

Import

import { Alert } from 'entangle-ui';

The compound members come along automatically:

<Alert>
  <Alert.Title>...</Alert.Title>
  <Alert.Description>...</Alert.Description>
  <Alert.Actions>...</Alert.Actions>
</Alert>

If you’d rather destructure, the same components are also exported as named imports:

import { Alert, AlertTitle, AlertDescription, AlertActions } from 'entangle-ui';

Usage

<Alert variant="warning" title="Read-only mode">
  Switch to edit mode to make changes.
</Alert>

A plain string in children is rendered as the description — no title needed for one-liners:

<Alert variant="info">Auto-save is on.</Alert>

Variants

The variant prop drives the color and the default icon.

Variants

Variant	Color token	Default icon	Role
info	colors.accent.primary	InfoIcon	status
success	colors.accent.success	CheckIcon	status
warning	colors.accent.warning	WarningIcon	alert
error	colors.accent.error	ErrorIcon	alert
neutral	colors.text.muted	(none)	region

<Alert variant="info" />
<Alert variant="success" />
<Alert variant="warning" />
<Alert variant="error" />
<Alert variant="neutral" />

Appearances

Three visual treatments. subtle is the default — and the right pick most of the time.

Appearances

Appearance	Treatment	When to use
subtle	Tinted background with a faint matching border	Default. Inline status without grabbing attention.
solid	Filled accent background, white text	High attention. Reserve for blocking errors / strong cues.
outline	Transparent background with a colored border	Quietest treatment. Useful in dense layouts.

<Alert variant="info" appearance="subtle" />
<Alert variant="info" appearance="solid" />
<Alert variant="info" appearance="outline" />

Without an icon

Pass icon={false} to drop the icon column, or pass any ReactNode to override the default.

Without icon

<Alert icon={false} variant="warning" title="Read-only">
  Switch to edit mode.
</Alert>

<Alert icon={<MyCustomIcon />} variant="info">
  Custom icon.
</Alert>

Dismissible

Provide onClose to render a close button in the top-right.

Dismissible

const [open, setOpen] = useState(true);

{
  open && (
    <Alert
      variant="success"
      title="Export complete"
      onClose={() => setOpen(false)}
    >
      The scene was exported successfully.
    </Alert>
  );
}

The close button is keyboard-reachable in the default tab order and uses aria-label="Close alert".

Compact

Title only, or description only — both work. The icon stays unless you opt out.

Compact

<Alert variant="info">Auto-save is on.</Alert>

With actions

Use Alert.Actions to render action buttons below the description.

With actions

<Alert variant="error" title="Couldn't reach the server">
  <Alert.Description>The request timed out after 30 seconds.</Alert.Description>
  <Alert.Actions align="right">
    <Button variant="filled" onClick={retry}>
      Retry
    </Button>
    <Button onClick={dismiss}>Dismiss</Button>
  </Alert.Actions>
</Alert>

The align prop controls horizontal placement: left (default), right, or space-between.

Long content

The body wraps naturally. Stack multiple Alert.Description blocks for paragraphs. Long unbroken strings — URLs, file paths, command snippets — are wrapped with overflow-wrap: anywhere, so the alert never pushes its container wider than intended.

Long content

Width

Alert defaults to width: 100% so it stretches to fill its parent and keeps a stable footprint regardless of content length. Override with the width prop — a number is treated as pixels, a string passes through as a CSS value.

<Alert width={420} variant="info">Fixed-width alert.</Alert>
<Alert width="32rem" variant="info">Sized to the type scale.</Alert>

Editor example

Pin a read-only warning above an inspector panel.

Editor example

Compound API

Alert exposes three compound members. They can be used as Alert.Title / Alert.Description / Alert.Actions, or imported as named exports (AlertTitle, etc.) — both refer to the same component.

<Alert variant="info">
  <Alert.Title>Heads up</Alert.Title>
  <Alert.Description>This is the body of the alert.</Alert.Description>
  <Alert.Actions>
    <Button>Dismiss</Button>
  </Alert.Actions>
</Alert>

If both the title prop and an <Alert.Title> child are supplied, both render — pick one.

Accessibility

• Role is derived from the variant: alert for error / warning (assertive), status for info / success (polite), region with an aria-label for neutral.
• The component doesn’t auto-focus. Inline alerts shouldn’t grab focus — that’s the job of Dialog and Toast.
• The icon is marked aria-hidden="true"; meaning is conveyed by the text and the role.
• The close button (when present) has aria-label="Close alert" and follows the default tab order.
• Color contrast meets WCAG AA across all five variants in both subtle and solid appearances on the dark theme.

Props

Alert

Prop	Type	Default	Description
variant	'info' | 'success' | 'warning' | 'error' | 'neutral'	'info'	Semantic intent. Drives color and the default icon.
appearance	'subtle' | 'solid' | 'outline'	'subtle'	Visual treatment.
icon	ReactNode | false	true	Icon at the start. `false` hides the icon; any ReactNode overrides the default.
onClose	() => void	—	When provided, renders a close button and calls this on click.
title	ReactNode	—	Convenience prop equivalent to wrapping with `<Alert.Title>`.
width	number | string	'100%'	Width of the alert. Number → px, string → CSS value. Defaults to filling the parent so the alert keeps a stable width regardless of content length; long strings wrap inside.
children	ReactNode	—	Compound children (Title / Description / Actions) or a plain string treated as the description.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the alert root element.

Alert.Title

Prop	Type	Default	Description
children	ReactNode	—	Title content.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the title element.

Alert.Description

Prop	Type	Default	Description
children	ReactNode	—	Description body content.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the description element.

Alert.Actions

Prop	Type	Default	Description
children	ReactNode	—	Action buttons.
align	'left' | 'right' | 'space-between'	'left'	Horizontal alignment of the action row.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the actions row element.