Toast

A notification system for displaying temporary messages with support for different severity levels, custom actions, and configurable positioning.

Import#

import { ToastProvider, useToast } from "asheeui";

Usage#

ToastProvider is a global feature provider. Wrap your application root once, placed strictly below <AsheeUIProvider>, then call toast functions from anywhere in your app.

import { AsheeUIProvider, ToastProvider, useToast, Button } from "asheeui";

function NotifyButton() {
	const { toast } = useToast();

	return <Button onClick={() => toast("Hello!")}>Notify</Button>;
}

export function App() {
	return (
		<AsheeUIProvider>
			{/* Feature providers MUST be placed below AsheeUIProvider */}
			<ToastProvider>
				<NotifyButton /> 
			</ToastProvider>
		</AsheeUIProvider>
	);
}

"use client";

import { ToastProvider, Button, useToast } from "asheeui";

function ToastTrigger() {
	const { success } = useToast();

	return (
		<div className="flex flex-wrap items-center gap-4">
			<Button onClick={() => success("Operation completed!")}>
				Show Success
			</Button>
		</div>
	);
}

export default function Basic() {
	return (
		<ToastProvider>
			<ToastTrigger />
		</ToastProvider>
	);
}

Examples#

Warning messages#

Info messages#

With title#

With custom icon#

Custom styling#

Style the toast container with the className prop on ToastProvider, and compose rich toasts with title, custom icon, and action elements.

With action button#

With custom timeout#

Non-dismissible#

Placement variants#

Size variants#

Variant#

Radius#

Max toasts#

Clearing all toasts#

Removing specific toast#

ToastProvider Props#

* Falls back through Global Configuration if not set. See below.

useToast API#

ToastShowOptions#

Portal Behavior#

The Toast container is rendered in a React portal by default. This means toasts are attached to document.body rather than staying in the component's DOM hierarchy.

Why use a portal?#

• Escapes CSS containment: Toasts appear above other content even when the ToastProvider is inside containers with overflow: hidden or contain: layout
• Avoids stacking context issues: Toasts maintain proper z-index regardless of parent stacking contexts
• Works with any parent: Toasts function correctly regardless of where the ToastProvider is placed in the component tree
• Prevents clipping: Toasts are never clipped by parent containers

When to disable the portal#

You may want to disable the portal (by setting portal={false}) when:

• You need toasts to stay within a specific container for testing purposes
• You are rendering inside a shadow DOM or iframe where document.body is not appropriate
• You have specific layout requirements that depend on toasts remaining in the DOM hierarchy

You can also provide a custom portalTarget to render toasts into a specific container instead of document.body.

Global Configuration#

Toast reads defaults from four places, in this order of precedence:

1. Instance prop: set directly on <ToastProvider />
2. Component config: components.toast in your ashee.config
3. Theme default: defaultVariant / defaultRadius in your ashee.config
4. Built-in fallback: component's internal default values

Component config#

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    toast: {
      size: "md",
      placement: "top-right",
      variant: "solid",
      radius: "md",
      defaultTimeout: 3500,
      maxToasts: 5,
      animated: true,
      portal: true,
    },
  },
};

Built-in fallbacks#

{
  size: "md",
  placement: "top-right",
  variant: "solid",
  radius: "md",
  animated: true,
  defaultTimeout: 3500,
  maxToasts: 5,
  portal: true,
}

Accessibility#

• Toast container has aria-label="Notifications"
• Toasts are keyboard focusable with proper focus management
• Dismiss buttons include aria-label="Dismiss notification"
• Toasts pause on hover for accessibility
• Respects reduced motion preferences
• Screen readers announce toast messages

Notes#

• Context Required: The ToastProvider must wrap your app root (placed below <AsheeUIProvider>) for toast functions to work.
• Type Mapping: Toast types (success, error, warning, info) automatically map to appropriate colors and icons.
• Pausable Timeout: Toasts pause their timeout when hovered, giving users more time to interact.
• Animation: Toasts animate in and out based on the placement prop. Disable with animated={false}.
• Max Toasts: When the maximum number of toasts is reached, older toasts are automatically removed.
• Dismissible: By default, toasts include a dismiss button. Set dismissible={false} to disable.
• Portal: Toasts are portaled to document.body by default. This can be disabled via the portal prop or component config.
• Per-Toast Customization: Each toast can override size, placement, variant, radius, and animation settings via ToastShowOptions.
• Solid Variant: When using the "solid" variant, the icon color automatically matches the toast's accent color.