Alert

A boxed message inside a page that calls out something the user should know.

This is an alert

Some information worth calling out.

1<template>2  <Alert variant="warning" title="Changes may be lost" description="You have unsaved changes." />3</template>

Props

Name	Type	Default
variant	'success' \| 'warning' \| 'error' \| 'default'	default
icon	string	one per variant, matching Figma (e.g. i-lucide-circle-alert for warning)
title	string	-
description	string	-
close	boolean \| object	-

Slots

Name	Description
title	Escape hatch: replaces the `title` prop's plain text.
description	Escape hatch: replaces the `description` prop's plain text - the usual way to add an inline link or button, e.g. `You've used all seats. <TextLink to="/billing">Upgrade</TextLink>`.
close	Escape hatch: replaces the default close button rendered when `close` is set.

Guidelines

Title or description only

Title and description when there's a headline and something more to say. The title names what happened or the current state as a short fragment (about 2 to 6 words, no period): "Seat limit reached", "Payment failed". The description says why, what it means or what to do next in 1 or 2 sentences, and holds any inline link. Use this for page-level alerts that compete for attention at the top of a page (billing, limits, trial notices).
Description only when the whole message is one thought (one sentence, about 20 words or fewer).
Inline alerts favour description only. Tell inline from page-level by what the alert is about, not where it sits. A page-level alert is about the page, the account or the organization as a whole ("Payment failed", "Seat limit reached") and would still make sense if the page around it changed. An inline alert is about the specific thing it sits in or next to (this token field, this repository, this step, this modal's results) and stops making sense without it. Placement usually follows: inline alerts sit inside that component's boundary, page-level ones span the content width at the top. Because an inline alert already sits next to its subject, a headline usually repeats the context; add a title only when it blocks the user and needs a headline to be noticed (a failed cost estimate that stops the scan wizard).
Never a title on its own: one thing to say is a description.
Never a full sentence as the title, and never a description that repeats the title.
Two sentences where the first is really a headline: split them into a title and a description.

Do

Use variant="warning" or variant="error" for something the user must act on before continuing (unsaved changes, a failed save, a limit reached).
Use variant="success" for a state change the user doesn't need to act on immediately.
Pass description as a slot (<template #description>) instead of a plain string when it needs an inline link - use TextLink for it. In a success/warning/error alert the link keeps the alert's own color; in a default alert it stays link blue. This is how Alert does a call-to-action that navigates. Anything that opens a modal or runs an action (Add payment method, Retry, Verify again) is a Button variant="secondary" size="sm", with no icon, in the #actions slot, which sits on the right, in the same row as the title and description. Use the slot rather than Nuxt UI's :actions array, so every alert button is the design system Button.

Reserve variant="default" for a callout that isn't state-specific (a tip, a note) rather than for a real success/warning/error that just doesn't feel urgent enough to color.
Override icon when the same variant/color needs a different glyph per audience or context (e.g. a warning banner that shows a different icon for owners vs. members) - the default only covers the generic case.

Don't

Don't stack more than one Alert in the same view for the same condition - pick the one that matters most and drop the rest.
Don't use Alert for transient, self-dismissing feedback (a save confirmation, an undo prompt) - use a toast (useToast()) instead; Alert is for state that persists until the user acts or the underlying condition changes.
Don't use Alert for something platform-wide that should follow the user across every page (a trial ending, a payment overdue) - Alert is page-wide, scoped to the page it's rendered on; use Banner instead.

Examples

Variants

success

A state change the user doesn't need to act on immediately.

Changes saved

Any pending edits are now up to date

1<template>2  <Alert variant="success" title="Changes saved" description="Any pending edits are now up to date" />3</template>

warning

Something the user should act on before continuing, without blocking them yet.

Unsaved changes

Save your work before leaving this page

1<template>2  <Alert variant="warning" title="Unsaved changes" description="Save your work before leaving this page" />3</template>

error

Something that failed and needs the user's attention.

Changes not saved

Something went wrong. Try again.

1<template>2  <Alert variant="error" title="Changes not saved" description="Something went wrong. Try again." />3</template>

default

A callout that isn't tied to a specific state - a tip or a note.

Note

For a callout that isn't tied to a state

1<template>2  <Alert variant="default" title="Note" description="For a callout that isn't tied to a state" />3</template>

Description only

One thought, or an alert about the thing it sits next to: no title, one row.

Changing the scope resets the cost estimate

1<template>2  <Alert variant="warning" description="Changing the scope resets the cost estimate" />3</template>

States

Dismissible

An alert the user can close once they've read it.

Seat limit reached

You've used all available seats

1<template>2  <Alert variant="warning" title="Seat limit reached" description="You've used all available seats" close />3</template>

With icons and slots

With inline link

A call to action that goes to another page: a TextLink at the end of the description.

Seat limit reached

You've used all available seats. Upgrade plan

1<template>2  <Alert variant="warning" title="Seat limit reached">3    <template #description>4      You've used all available seats.5      <TextLink to="/billing">Upgrade plan</TextLink>6    </template>7  </Alert>8</template>

With a button

A call to action that opens a modal or runs an action (Add payment method, Retry): a Button in the #actions slot, on the right. Shown in every variant.

Changes saved

Any pending edits are now up to date

Unsaved changes

Your edits will be lost if you leave this page

Changes not saved

Something went wrong with the last save

Note

A newer version of this page is available

1<template>2  <Alert variant="success" title="Changes saved" description="Any pending edits are now up to date">3    <template #actions>4      <Button variant="secondary" size="sm">5        Undo6      </Button>7    </template>8  </Alert>9  10  <Alert variant="warning" title="Unsaved changes" description="Your edits will be lost if you leave this page">11    <template #actions>12      <Button variant="secondary" size="sm">13        Save14      </Button>15    </template>16  </Alert>17  18  <Alert variant="error" title="Changes not saved" description="Something went wrong with the last save">19    <template #actions>20      <Button variant="secondary" size="sm">21        Retry22      </Button>23    </template>24  </Alert>25  26  <Alert variant="default" title="Note" description="A newer version of this page is available">27    <template #actions>28      <Button variant="secondary" size="sm">29        Reload30      </Button>31    </template>32  </Alert>33</template>