Alert

Overview

Alert communicates system status — success, error, warning, or info — in a way that is immediately visible and contextual. It displays as a contextual banner with a color-coded left border (or background), an optional title, a concise message, and an optional dismiss button. Alert is used for form validation summaries, success confirmations, destructive action warnings, and system-wide notices across Byteion dashboards, admin panels, ecommerce back offices, ERP/POS workflows, and starter kits.

Why this exists

Without a shared Alert pattern, teams build ad-hoc status messages with inconsistent colors, font sizes, and icon choices. Some use bg-green-100 text-green-800, others use random card styles, and the correct role="alert" attribute is often missing, leaving screen reader users unaware of important feedback. Alert unifies system messages into a consistent, accessible, token-based system with four severity levels, optional dismissal, and proper ARIA support.

Mental model

• Alert is system-generated — it communicates application state, not user content. Think form errors, save confirmations, and connectivity warnings.
• Severity drives color — success (green), danger (red), warning (amber), and info (blue). Each tone has a semantic meaning that should not be reused for other purposes.
• Alert vs Toast — alert stays inline on the page and persists until dismissed. Toast appears temporarily in a corner and auto-dismisses.
• Alert is not Blockquote — blockquote shows quoted content from a person or source. Alert is for system messages only.

When to use

• Form validation summary — top-of-form alert listing error counts and guidance
• Success confirmation — "Changes saved", "Backup completed", "Order placed" after an action
• Warning before destructive actions — "Deleting this project will remove all associated data"
• System-wide notices — maintenance windows, API outages, rate limit warnings
• Empty state guidance — "No results found" with contextual suggestions (when paired with Empty State component)

When not to use

• Do not use alerts for transient notifications — use Toast for messages that should auto-dismiss
• Do not use alerts for marketing or callout content — use a card or callout section instead
• Do not stack multiple alerts — combine errors into a single summary alert or use toast for low-priority messages
• Do not use danger for non-blocking issues — reserve red/danger for actual blocking errors
• Do not use alerts for quoted content — use Blockquote for testimonials and cited prose

Basic example

All four severity levels rendered as inline banners with an icon, title, and message:

<div class="flex items-start gap-3 rounded-lg border border-info/30 bg-info/5 p-4" role="alert">
  <i class="ti ti-info-circle text-info text-xl mt-0.5"></i>
  <div>
    <p class="text-sm font-semibold text-info">Heads up</p>
    <p class="text-sm text-info/80 mt-1">New billing cycle starts next Monday.</p>
  </div>
</div>

Alert vs Toast vs Blockquote

Variants

Alert has four severity variants, each with a distinct color mapping:

Dismissible alert

Non-critical alerts can include a dismiss button. Dismissible alerts should provide a visual close affordance and require JavaScript to handle the dismiss action:

Anatomy

• Container — rounded rectangle with left-border accent (via border-l-*) or background tint (bg-{tone}/5)
• Icon — Tabler icon that matches the severity tone
• Title — optional bold summary (e.g., "Payment failed")
• Message — detailed description in the same tone at 80% opacity
• Dismiss button — optional <button> with an aria-label="Dismiss" for non-critical alerts
• role="alert" — announces the alert to screen readers immediately

Usage guidelines

• Use danger alerts only for errors that block progress — do not use red for warnings
• Use success alerts to confirm completed actions and give users confidence their action worked
• Keep warning alerts for recoverable issues that users can fix without data loss
• Provide a dismiss button for non-critical alerts (info, success) so users can clear them
• Do not provide a dismiss button for blocking errors — users must resolve the issue first
• Place form validation alerts at the top of the form, not next to each field
• Keep the title short (2–4 words) and the message concise (1–2 sentences)

Do and Don't

Accessibility

Alert follows the WAI-ARIA Alert pattern:

• role="alert" — announces the alert to screen readers immediately on render. Do not use aria-live — role="alert" is sufficient
• Dismiss button — must be a native <button> element with aria-label="Dismiss"
• Color is not the only indicator — always include an icon and text label. Screen reader users rely on the text, not the color
• Focus management — when a critical alert appears (form validation), consider moving focus to the alert container so screen reader users can hear the message
• Consecutive alerts — if multiple alerts fire, announce each one. Use a polite aria-live="polite" region to queue announcements from dynamic alerts

Customization

Alert colors map to Byteion semantic tokens: --success, --danger, --warning, and --info. Each alert uses border-{tone}/30, bg-{tone}/5, and text-{tone} for consistent layering. Customize border style (left accent vs full border), border radius, and icon set via standard Tailwind classes. The icon component and title can be omitted for compact single-line alerts.

HTML example

<!-- Success alert -->
<div class="flex items-start gap-3 rounded-lg border border-success/30 bg-success/5 p-4" role="alert">
  <i class="ti ti-circle-check text-success text-xl mt-0.5"></i>
  <div>
    <p class="text-sm font-semibold text-success">Saved</p>
    <p class="text-sm text-success/80 mt-1">Your changes are now live.</p>
  </div>
</div>

<!-- Danger alert with dismiss -->
<div class="flex items-start gap-3 rounded-lg border border-danger/30 bg-danger/5 p-4" role="alert">
  <i class="ti ti-alert-circle text-danger text-xl mt-0.5"></i>
  <div class="flex-1">
    <p class="text-sm font-semibold text-danger">Payment failed</p>
    <p class="text-sm text-danger/80 mt-1">Update your billing details to continue.</p>
  </div>
  <button class="text-danger/60 hover:text-danger" aria-label="Dismiss">
    <i class="ti ti-x text-lg"></i>
  </button>
</div>

<!-- Warning alert -->
<div class="flex items-start gap-3 rounded-lg border border-warning/30 bg-warning/5 p-4" role="alert">
  <i class="ti ti-alert-triangle text-warning text-xl mt-0.5"></i>
  <div>
    <p class="text-sm font-semibold text-warning">API rate limit nearing</p>
    <p class="text-sm text-warning/80 mt-1">86% of monthly quota used.</p>
  </div>
</div>

React example

React exports <Alert> from @byteion/react. Use the tone prop for severity, title for the heading, and dismissible for a close button:

import { Alert } from '@byteion/react';

export default function AlertDemo() {
  return (
    <div className="space-y-3">
      <Alert tone="info" title="Heads up">
        New billing cycle starts next Monday.
      </Alert>
      <Alert tone="success" title="Backup completed">
        Your workspace has been backed up to the secondary region.
      </Alert>
      <Alert tone="warning" title="API rate limit nearing">
        You have used 86% of your monthly quota.
      </Alert>
      <Alert tone="danger" title="Payment failed" dismissible onDismiss={() => {}}>
        The card on file was declined. Update your billing details.
      </Alert>
    </div>
  );
}

Vue example

Vue exports <Alert> from @byteion/vue with the same tone and title props:

<script setup lang="ts">
import { Alert } from '@byteion/vue';
</script>

<template>
  <div class="space-y-3">
    <Alert tone="info" title="Heads up">
      New billing cycle starts next Monday.
    </Alert>
    <Alert tone="success" title="Backup completed">
      Your workspace has been backed up to the secondary region.
    </Alert>
    <Alert tone="warning" title="API rate limit nearing">
      You have used 86% of your monthly quota.
    </Alert>
    <Alert tone="danger" title="Payment failed" dismissible>
      The card on file was declined. Update your billing details.
    </Alert>
  </div>
</template>

API Reference

The Alert component is available in @byteion/react and @byteion/vue:

Developer tips

• Use role="alert" for dynamic alerts — when an alert appears after a user action (form submit, delete), ensure it has role="alert" so screen readers announce the new content
• Consider focus management for critical alerts — when a form validation alert appears, move focus to the alert so keyboard and screen reader users hear it immediately
• Keep the title consistent across similar scenarios — use the same title wording for save confirmations, the same for validation errors, so users learn the pattern
• Do not stack multiple alerts — if validation fires 5 errors, combine them into one summary alert with a list
• Use toast for non-blocking confirmations — "Changes saved" with auto-dismiss is better as a Toast. Reserve Alert for messages that need user attention
• Map alert tones to your application's status system — ensure the API response status maps cleanly to success, danger, warning, and info

Common mistakes

• Using danger for warnings — users learn that red equals blocking. Using red for non-blocking issues trains them to ignore real errors
• Stacking multiple alerts — multiple alerts on a page create visual noise. Combine related messages into one summary
• Missing role="alert" — without role="alert", screen readers may not announce dynamic alert content
• Using alerts for marketing or callouts — system status messages and marketing callouts have different visual purposes. Use cards or banners for callouts
• Using alerts for transient notifications — Toast is better for messages that auto-dismiss. Alert stays inline and requires manual dismissal
• Making all alerts dismissible — blocking errors (danger) should not be dismissible. Users must resolve the issue before the alert goes away

Production usage tips

• Test form validation state management — verify that alerts appear when validation fires and disappear when errors are resolved
• Test dismiss behavior — verify the dismiss button hides the alert and that refiring the action shows it again
• Test dark mode and branded themes — alert colors use semantic tokens that adapt to dark mode and brand themes
• Test screen reader announcements — verify that role="alert" announces the alert content on dynamic insertion
• Test alert stacking prevention — ensure the application does not produce duplicate alerts for the same event
• Keep React and Vue APIs aligned with the core HTML schema — tone, title, and dismissible props map to HTML class structures

Premium examples

Pro patterns available in Byteion Pro:

• Animated alert with slide-in — alert slides in from the top or left with a smooth CSS animation for dynamic form feedback
• Alert with inline retry action — danger alerts that include a "Retry" button for network-related failures
• Stacked alert queue with auto-rotate — a fixed-position alert stack that shows one alert at a time, rotating through queued messages
• Form validation summary alert — top-of-form alert with a numbered list of field errors, each linking to the relevant input
• Ecommerce checkout alert — shipping delay warning, coupon applied confirmation, and payment error in a stacked checkout alert area
• ERP / POS system alert — low stock warning, sync failure alert, and daily sales summary in the admin notification area

Related components

• Toast — transient notifications that auto-dismiss for non-blocking messages
• Blockquote — quoted prose with attribution, not system messages
• Badge — compact status labels for inline state indicators
• Modal — blocking dialog for critical confirmations
• Empty State — placeholder for empty data with guidance and action

API Reference

Related components

• Toast
• Badge
• Modal
• Empty State

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX