Toast

Transient notification with auto-dismiss and variant support. Declarative or programmatic.

Overview

The Toast component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Toasts communicate transient messages that do not require immediate action. They appear, auto-dismiss, and stack when multiple fire at once.

Mental model

A toast is a temporary notification. It appears in a corner, shows for 3-5 seconds, and fades. Users should not need to dismiss it.

When to use

• Save confirmation ("Changes saved") • Copy confirmation ("Link copied") • Background task complete ("Export ready") • Non-blocking error ("Could not connect")

When not to use

• Do not use for errors that require action — use an alert • Avoid for critical messages — use a modal • Do not use for messages the user must acknowledge

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

Variants

Each variant communicates a different meaning. Choose based on priority, not aesthetics.

Single default variant.

Sizes

Size should match the importance and context of the component.

  • md — md size.

States

This component reacts seamlessly to the following interaction and data states:

  • visible — Rendered and interactive.
  • hidden — Not rendered in the DOM.
  • default — Resting appearance before interaction.
  • hover — Pointer is over the element — visual feedback via color or shadow.
  • focus — Keyboard or tab focus — shows ring indicator for accessibility.
  • active — Currently selected or in use.
  • disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

• Container — fixed position, stacked • Icon — communicates type • Message — concise text • Action — optional (Undo, Retry) • Close button — optional • Progress bar — auto-dismiss timer

Usage guidelines

  • Auto-dismiss after 3-5 seconds.
  • Keep messages under 10 words.
  • Provide an action only when reversal is possible (Undo).

Do and Don't

Do

  • Auto-dismiss.
  • Keep messages short.
  • Provide Undo when possible.

Don't

  • Do not stack more than 3 toasts.
  • Do not require dismissal.
  • Do not use for critical errors.
  • Do not play sound.

Accessibility

Toasts use aria-live="polite" so screen readers announce them. They do not steal focus.

Role:status (default) or alert (for errors)

ARIA Attributes

  • aria-live
  • role

Keyboard Navigation

  • Escape
  • Tab

Customization

Position and colors follow toast tokens.

Compose with React cva()

Use the exportedcva() +cn() utilities to compose your own variant on top of the Byteion tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myToast = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myToast>;

Compose with Vue cva()

Use the exportedcva() +cn() utilities inside standard Vue setup blocks.

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myToast = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myToast({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

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

HTML / JS events

  • bi:toast:hide
  • bi:toast:show

React callbacks

No React callback events are declared by this adapter.

Vue emits

No Vue emitted events are declared by this adapter.

Remote / AJAX

This component does not implement Byteion JS remote loading. Use normal HTML form submission, framework state, or your application data layer around it.

API Reference

Programmatic API: toast.success(), toast.error(), toast.info().

HTML Data Attributes

  • data-bi-toast

Developer tips

• Best practice: always offer"Undo" for destructive actions — it is better than a confirmation dialog. • Edge case: on mobile, toasts should appear at the bottom (thumb zone).

Common mistakes

Avoid hardcoded neutral colors, placeholder-only labels, duplicated primary actions, and missing keyboard states. Keep this component on Byteion tokens so dashboard, admin, POS, ERP, ecommerce back-office, Laravel, React, and Vue starter-kit screens can be rebranded without rewriting markup.

Production usage tips

Use the canonical HTML as the source of truth, keep React and Vue wrappers aligned with the documented variants, test dark mode and branded themes before release, and wire interactive behavior through data-bi-* attributes instead of styling hooks.

Premium examples

Advanced patterns available in Byteion Pro:

• Toast with progress bar and swipe-to-dismiss • Toast action button (Undo, View) • Stacked toast queue with collapse/expand

Unlock Premium Patterns

Get access to copy-paste ready Pro blocks, SaaS templates, and advanced data-tables built with this component.

Explore Pro Components