Toast

Imperative, stackable toast notifications with positioning, auto-dismiss timers, swipe-to-dismiss, promise tracking, and full theme/animation control.

Quick Usage

Call `useToast()` from anywhere inside a `<ToastProvider>` to imperatively show a toast. Remember to wrap your app in `ThemeProvider` (see the Theming page) so `color` and `variant` resolve correctly.

import React from 'react';
import { useToast } from '@bytesui/react';

export default function ToastExample() {
  const { show } = useToast();

  return (
    <button
      onClick={() =>
        show({
          title: 'Saved',
          message: 'Your changes have been saved successfully.',
          color: 'success',
        })
      }
    >
      Save
    </button>
  );
}

Step-by-Step Integration

Follow these steps to wire up toasts in a new application.

npm install @bytesui/react

Interactive Demo — All Variants & Live Controls

A single sandbox showcasing every color, variant, position, and animation preset, plus live controls to configure a toast and fire it, or run the loading → success/error promise flow.

Color & Variant

Every toast accepts `color` (one of the 8 semantic colors, default `'primary'`) and `variant` (`solid` | `outlined` | `soft` | `plain`, default `'soft'`).

import { useToast } from '@bytesui/react';

function ColorVariantExample() {
  const { show } = useToast();

  return (
    <>
      <button onClick={() => show({ message: 'Solid warning', color: 'warning', variant: 'solid' })}>Solid</button>
      <button onClick={() => show({ message: 'Outlined info', color: 'info', variant: 'outlined' })}>Outlined</button>
      <button onClick={() => show({ message: 'Soft success', color: 'success', variant: 'soft' })}>Soft</button>
      <button onClick={() => show({ message: 'Plain neutral', color: 'neutral', variant: 'plain' })}>Plain</button>
    </>
  );
}

Positions & Duration

Toasts stack in one of 6 screen corners via `position` (defaults to the provider's `defaultPosition`, `'top-right'`). `duration` controls auto-dismiss in ms; pass `null` to keep a toast visible until manually dismissed. `maxVisible` on `ToastProvider` limits how many toasts show per position at once, queuing the rest.

import { useToast } from '@bytesui/react';

function PositionDurationExample() {
  const { show } = useToast();

  return (
    <>
      <button onClick={() => show({ message: 'Bottom-left, 2s', position: 'bottom-left', duration: 2000 })}>
        Bottom Left (2s)
      </button>
      <button onClick={() => show({ message: 'Sticky until dismissed', position: 'top-center', duration: null })}>
        Sticky Toast
      </button>
    </>
  );
}

Animations

import { useToast } from '@bytesui/react';

function AnimationExample() {
  const { show } = useToast();

  return (
    <>
      <button onClick={() => show({ message: 'Fades in/out', animation: 'fade' })}>Fade</button>
      <button
        onClick={() =>
          show({
            message: 'Custom slide distance & easing',
            animation: { type: 'slide', duration: 350, distance: 48, easing: 'cubic-bezier(0.22, 1, 0.36, 1)' },
          })
        }
      >
        Custom Slide
      </button>
    </>
  );
}

Promise Toasts

`promise()` shows a loading toast and automatically transitions it to success/error once the given promise settles. `success`/`error` messages can be a static value, `ToastOptions`, or a function of the resolved data/error.

import { useToast } from '@bytesui/react';

function PromiseExample({ saveUser }) {
  const { promise } = useToast();

  const handleClick = () => {
    promise(saveUser(), {
      loading: 'Saving user\u2026',
      success: (user) => ({ title: 'Saved', message: `${user.name} was saved.` }),
      error: (err) => ({ title: 'Save failed', message: err.message, color: 'error' }),
    });
  };

  return <button onClick={handleClick}>Save User</button>;
}

Slot Styling

Use the `style` prop on `show()`/`update()` options with `Bui.*` slot keys to override specific parts of a single toast without extra CSS.

import { useToast } from '@bytesui/react';

function SlotStylingExample() {
  const { show } = useToast();

  return (
    <button
      onClick={() =>
        show({
          title: 'Custom styled toast',
          message: 'Slot overrides applied to root, title, and close button.',
          color: 'primary',
          style: {
            'Bui.root': { borderRadius: '16px', boxShadow: '0 8px 24px rgba(0,0,0,0.18)' },
            'Bui.title': { fontSize: '15px', fontWeight: '700' },
            'Bui.closeButton': { color: '#6b7280' },
          },
        })
      }
    >
      Show Styled Toast
    </button>
  );
}

ToastProvider Props

Prop	Type	Default	Description
`children`	ReactNode	`—`	App content rendered inside the provider.
`defaultPosition`	ToastPosition	`"top-right"`	Default stack position for toasts that don't specify one.
`defaultDuration`	number	`5000`	Default auto-dismiss delay in ms.
`maxVisible`	number	`3`	Maximum toasts visible per position at once; extras wait in a queue until space frees up.
`newestOnTop`	boolean	`false`	When false, new toasts queue behind existing ones and are shown/dismissed in FIFO arrival order. Set to true to show new toasts immediately, pushing older ones to the back of the queue.
`portalContainer`	HTMLElement	`document.body`	DOM node to portal toast containers into.
`defaultAnimation`	ToastAnimation	`"slide"`	Default enter/exit animation for toasts that don't specify their own.
`customToast`	(toast: ToastItem) => ReactNode	`undefined`	Customize how every toast renders (still gets swipe/dismiss/timer behavior). Overridden per-toast by that toast's own `render` option.

Toast Options (show / update)

Prop	Type	Default	Description
`id`	string	`auto-generated`	Stable id; pass an existing id to `show()` to replace that toast.
`title`	ReactNode	`undefined`	Toast title.
`message`	ReactNode	`undefined`	Toast body message.
`icon`	ReactNode	`undefined`	Leading icon element.
`color`	'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'error' \| 'neutral' \| 'info'	`"primary"`	Semantic color, resolved from the active theme.
`variant`	'solid' \| 'outlined' \| 'soft' \| 'plain'	`"soft"`	Visual style variant.
`position`	ToastPosition	provider's `defaultPosition`	Stack corner to render in.
`duration`	number \| null	provider's `defaultDuration`	Auto-dismiss delay in ms. Pass `null` to disable auto-dismiss.
`dismissible`	boolean	`true`	Show the manual close (×) button and allow swipe-to-dismiss.
`animation`	ToastAnimation	provider's `defaultAnimation`	Enter/exit animation for this toast; a preset name or a `ToastAnimationConfig` object.
`action`	{ label: string; onClick: () => void }	`undefined`	Action button rendered in the toast; clicking it also dismisses the toast.
`onDismiss`	() => void	`undefined`	Called once when the toast is dismissed (manually, by timeout, or by swipe).
`render`	(toast: ToastItem) => ReactNode	`undefined`	Fully custom content for this toast only; bypasses the default layout and any provider-level `customToast`.
`style`	ToastSlotStyle	`undefined`	Slot-based style overrides keyed by `Bui.*` slot names. See the slots reference below.

useToast() API

Method	Type	Description
`show`	(options: ToastOptions) => string	Show a new toast, returns its id.
`update`	(id: string, options: Partial<ToastOptions>) => void	Merge new options into an existing toast (e.g. to transition loading → success).
`dismiss`	(id: string) => void	Dismiss a single toast by id.
`dismissAll`	(position?: ToastPosition) => void	Dismiss every toast, optionally scoped to a single position.
`promise`	<T>(promise: Promise<T>, messages: ToastPromiseMessages<T>, options?: Partial<ToastOptions>) => Promise<T>	Show a loading toast that resolves to success/error based on the given promise.
`pause`	(id: string) => void	Pause a toast's auto-dismiss timer (used internally on hover/drag).
`resume`	(id: string) => void	Resume a previously paused toast's auto-dismiss timer.

Toast Style Slots

Slot	Description
`Bui.root`	Toast card container.
`Bui.icon`	Leading icon wrapper.
`Bui.content`	Wrapper around title and message.
`Bui.title`	Toast title text.
`Bui.message`	Toast message text.
`Bui.action`	Action button, when `action` is provided.
`Bui.closeButton`	Manual dismiss (×) button, when `dismissible` is true.