Toast

Show toast

Contract

Overview

Machine-readable contract from Component Spec.

component: toastexport: Toastversion: 1recipe: toasttokens.visual: toastattributes: data-refineui=toast

Anatomy

Part	data-refineui
root	toast
icon	toast-icon
item	toast-item
scale_layer	toast-scale-layer
toaster	toaster

Variants

Axis	Values
variant	default, success, error, warning

States

Scope	Category	Values
component	environment	forced-colors, dir, prefers-contrast

Accessibility

Slot	Element	Role
toast	div	status

Layout

Property	Value
direction	logical
rtl	true

Tokens

Variant

Select a recipe variant — preview and Recipe → Tokens update together.

Variant

Select...󰯑

Show toast

Recipe → Tokens

Slot bindings for variant="success" — declared in toast.recipe.ts.

Slot	Variant	Property	Trace	Semantic	Light → foundation	Dark → foundation	Recipe class
root	—	background	toast.background	surfacePopover	neutralWhite	neutral750	bg-refineui-alias-surface-popover
message	—	foreground	toast.message	foregroundPrimary	primaryBlack	neutralWhite	text-refineui-alias-foreground-primary
icon	success	foreground	toast.accent.success	foregroundSuccess	green700	green200	text-refineui-alias-foreground-success

Component token trace

All paths in token-trace-v2.json prefixed with toast.

Trace	Semantic	Light foundation	Dark foundation	Light	Dark
toast.accent.default	foregroundPrimary	primaryBlack	neutralWhite	#212121	#FFFFFF
toast.accent.error	foregroundError	red700	red200	#D93A3A	#FFC3C3
toast.accent.success	foregroundSuccess	green700	green200	#1D8822	#5BEE62
toast.accent.warning	foregroundWarning	yellow700	yellow200	#967000	#FFCB2F
toast.background	surfacePopover	neutralWhite	neutral750	#FFFFFF	#333333
toast.message	foregroundPrimary	primaryBlack	neutralWhite	#212121	#FFFFFF

Installation

npmyarnpnpmbun

npm install @refineui/react @refineui/tokens

Usage

import { Toast, Toaster, toast } from "@refineui/react";

// Add Toaster to your app root (one toast at a time by default)
<Toaster />

// Show a toast — replaces any currently visible toast
toast("Settings saved successfully", {
  variant: "success",
  duration: 3000,
});

toast("Upload failed", {
  variant: "error",
  action: {
    label: "Retry",
    onClick: () => retryUpload(),
  },
});

Swipe or drag the toast upward to dismiss it early.

API Reference

Toast

Prop	Default	Type	Description
variant	"default"	"default" | "success" | "error" | "warning"	Toast visual variant.
message	—	ReactNode	Toast message.
icon	—	ReactNode	Custom icon element.
iconName	—	string	Icon name (when not using icon).
action	—	ReactNode | ToastAction	Action button or custom element.

Toaster

Prop	Default	Type	Description
maxToasts	1	number	Maximum simultaneous toasts. Default replaces the previous toast.
swipeDirections	["top"]	("top" | "right" | "bottom" | "left")[]	Allowed swipe-to-dismiss directions.

toast(message, options)

Function to show a toast programmatically. A new call replaces the previous toast.

Options:

• variant?: ToastVariant — Visual variant
• icon?: ReactNode — Custom icon
• action?: ToastAction — Action button
• duration?: number — Duration in milliseconds (default 4200)