Skip to content

The status message that stays on the page until someone reads it or closes it.

import { BbAlert } from 'bitboss-ui';

On this page

Use it for

Reach for BbAlert when the message stays on the page: errors above a form, a quota warning, a "saved" confirmation in the panel that produced it.

Use something else when

  • BbToast with useToast, when the feedback is momentary and follows an action
  • BbConfirm with useConfirm, when you are asking the user to decide
  • BbBadge, when it is a count or a state attached to another element

Also see: Design language.

Passthrough

Hover or tap a part to outline it. The toggles turn on loading, errors and warnings where the component has them; only parts get a row.

Heads up

Communicate a page state

Stack page-level messages at the top of the page they belong to, most urgent first.

Billing

Storage almost full
46 of 50 GB used. Uploads stop when storage is full.
Localized invoices
Invoices can now be issued in Italian, German and French.
Plan
Team, billed monthly
Card
Visa ending 4242

Use hide-close when the message clears only after the underlying state is fixed. The shortest form puts the body in the default slot, <BbAlert>Something went wrong</BbAlert>. When a string is all you have, pass it as text.

Variants

Pick the variant by intent, not decoration:

  • outline for neutral information
  • primary for a branded note that asks for action, such as an upgrade
  • warning for something the user should attend to
  • destructive for a failure
Prices exclude VAT
The catalogue shows net prices; VAT is added at checkout.
Turn on low-stock emails
Stock now refreshes every 15 minutes, soon enough to warn you before a product sells out.

outline is the default. No variant brings an icon of its own, so pair the variant with an icon, and pair them once: the object form of alertVariants sets each variant's icon for the whole app (Custom variants).

There is no success or info alert. A confirmation is usually a toast, a neutral note is outline with an icon, and anything else you register yourself.

Coming from v2theme → variant

In v2 theme took any string and painted nothing: v2 shipped no .bb-alert--* rules at all. In v3 the string is live, and theme="warning" becomes an amber alert, quietly. Grep your stylesheets for .bb-alert--<value>: if nothing styled it, drop the prop.

Validation summaries

A destructive alert above the form, appearing on the first failed submit and listing what is missing. Give it hide-close: the user clears this message by fixing the fields.

Inside a BbForm, read errors and submitCount from its slot. The summary lists the messages each field already shows under itself, and a failed submit still moves focus to the first invalid field. Keep it to one summary rather than an alert per field.

Dismissal and v-model

The close button renders by default and works without a v-model. For a message nobody should be able to close, use hide-close. Name the button for the message with close-label when "Close" alone would be vague.

Verify your email
We sent a link to [email protected]. It expires in 24 hours.

Bind v-model to observe the state and to put the alert back: setting it to true replays the same transition inward. The alert owns its own visibility, so it needs no wrapping v-if.

Coming from v2show-close → hide-close

The polarity flipped: :show-close="false" becomes hide-close, and a show-close left at its default is deleted. In development the library warns when it still finds a v2 name on the component.

Rich content

The #title and #text slots replace the heading and the body. Both receive { text }, so you can decorate the string you were handed instead of restating it.

You are on the Free plan
Vantera Free keeps three active projects. Compare plans

Three sources can supply the body, and the most specific wins: #text, then child content, then the text prop. There is no actions slot: a real anchor in the text is fine, anything more interactive belongs outside the alert.

Coming from v2

The #text slot's scope used to hand you the title by mistake. It now carries the text, so any workaround that read the prop from outside the slot can go.

How an alert is announced

warning and destructive announce as role="alert" and aria-live="assertive". Every other variant uses role="status" and aria-live="polite".

Force either one with the role prop when visual tone and urgency come apart. The role brings its politeness along (alert is assertive, status polite); aria-live is for the rare case that needs the two to differ.

vue
<BbAlert
    role="alert"
    icon="lucide:cloud-off"
    title="Autosave failed"
    text="Your last edits exist only on this device."
/>

Never let several assertive alerts appear at once: they cut each other off.

Coming from v2

The alert is always aria-atomic, so a changed list re-announces whole. The v2 prop that turned that off is gone.

Custom variants

Register a name in the plugin's alertVariants and it becomes a typed value of variant.

ts
// nuxt.config.ts
export default defineNuxtConfig({
    bitboss: { alertVariants: ['success'] },
});

The object form registers the names and sets each variant's icon for the whole app; a built-in name only gets its icon:

ts
// nuxt.config.ts
export default defineNuxtConfig({
    bitboss: {
        alertVariants: {
            warning: { icon: 'lucide:triangle-alert' },
            destructive: { icon: 'lucide:circle-x' },
            success: { icon: 'lucide:circle-check' }, // a project variant
        },
    },
});

An alert without its own icon shows its variant's, its own icon wins, and hide-icon hides either:

vue
<BbAlert variant="warning" title="Heads up" />
<BbAlert variant="warning" icon="lucide:clock" title="Runs at midnight" />
<BbAlert variant="warning" hide-icon title="Plain" />

Registered variants ship no CSS. You paint .bb-alert--<name> yourself with the locals the built-ins set: --fg for the title and the icon (the body and the close button follow it at 75%), --bg and --border-color for the fill and the border. Mix from a theme token such as --bb-success, which stays legible in dark mode.

css
.bb-alert--success {
    --fg: color-mix(in oklab, var(--bb-success) 55%, var(--bb-text));
    --border-color: color-mix(
        in oklab,
        var(--bb-success) 35%,
        var(--bb-panel)
    );
}

A registered variant is polite however alarming its name. Pass role="alert" on the instances that genuinely are urgent.