1'use client';23import { Button } from '@/components/ui/button';4import { Toast, useToast } from '@/components/ui/toast';56function ToastDemo() {7 const { toast } = useToast();89 return (10 <Button11 variant="outline"12 onClick={() =>13 toast({14 title: 'Event created',15 description: 'Your event has been created successfully.',16 })17 }18 >19 Show Toast20 </Button>21 );22}2324export function Default() {25 return (26 <Toast.Provider>27 <ToastDemo />28 </Toast.Provider>29 );30}
Installation
pnpm dlx mateui add toast
Anatomy
1import { Toast, useToast } from '@/components/ui/toast';
Wrap your app with
Toast.Provider, then use useToast() anywhere:1function App() {2 return (3 <Toast.Provider>4 <MyComponent />5 </Toast.Provider>6 );7}89function MyComponent() {10 const { toast } = useToast();1112 return <button onClick={() => toast({ title: 'Hello!' })}>Show Toast</button>;13}
Variants
Default
1'use client';23import { Button } from '@/components/ui/button';4import { Toast, useToast } from '@/components/ui/toast';56function ToastDemo() {7 const { toast } = useToast();89 return (10 <Button11 variant="outline"12 onClick={() =>13 toast({14 title: 'Event created',15 description: 'Your event has been created successfully.',16 })17 }18 >19 Show Toast20 </Button>21 );22}2324export function Default() {25 return (26 <Toast.Provider>27 <ToastDemo />28 </Toast.Provider>29 );30}
All Variants
Five built-in variants:
default, success, error, info, and warning.1'use client';23import { Button } from '@/components/ui/button';4import { Toast, useToast } from '@/components/ui/toast';56function VariantsDemo() {7 const { toast } = useToast();89 return (10 <div className="flex flex-wrap gap-2">11 <Button12 variant="outline"13 onClick={() =>14 toast({ title: 'Default notification', description: 'This is a default toast.' })15 }16 >17 Default18 </Button>19 <Button20 variant="outline"21 onClick={() =>22 toast({23 title: 'Success!',24 description: 'Your changes have been saved.',25 variant: 'success',26 })27 }28 >29 Success30 </Button>31 <Button32 variant="outline"33 onClick={() =>34 toast({35 title: 'Error',36 description: 'Something went wrong. Please try again.',37 variant: 'error',38 })39 }40 >41 Error42 </Button>43 <Button44 variant="outline"45 onClick={() =>46 toast({47 title: 'Info',48 description: 'A new version is available.',49 variant: 'info',50 })51 }52 >53 Info54 </Button>55 <Button56 variant="outline"57 onClick={() =>58 toast({59 title: 'Warning',60 description: 'Your session is about to expire.',61 variant: 'warning',62 })63 }64 >65 Warning66 </Button>67 </div>68 );69}7071export function Variants() {72 return (73 <Toast.Provider>74 <VariantsDemo />75 </Toast.Provider>76 );77}
With Action
Toast with an action button.
1'use client';23import { Button } from '@/components/ui/button';4import { Toast, useToast } from '@/components/ui/toast';56function WithActionDemo() {7 const { toast } = useToast();89 return (10 <Button11 variant="outline"12 onClick={() =>13 toast({14 title: 'Message sent',15 description: 'Your message has been sent successfully.',16 action: {17 label: 'Undo',18 onClick: () => {19 // undo action20 },21 },22 })23 }24 >25 Show Toast with Action26 </Button>27 );28}2930export function WithAction() {31 return (32 <Toast.Provider>33 <WithActionDemo />34 </Toast.Provider>35 );36}
Positions
Choose where toasts appear on screen. Click a position to select it, then trigger a toast.
1'use client';23import * as React from 'react';4import { Button } from '@/components/ui/button';5import { Toast, useToast, type ToastPosition } from '@/components/ui/toast';67const positions: { label: string; value: ToastPosition }[] = [8 { label: 'Top Left', value: 'top-left' },9 { label: 'Top Right', value: 'top-right' },10 { label: 'Bottom Left', value: 'bottom-left' },11 { label: 'Bottom Right', value: 'bottom-right' },12];1314function PositionsInner() {15 const { toast } = useToast();1617 return (18 <Button19 variant="outline"20 onClick={() =>21 toast({22 title: 'Notification',23 description: 'Check the position of this toast.',24 })25 }26 >27 Show Toast28 </Button>29 );30}3132export function Positions() {33 const [position, setPosition] = React.useState<ToastPosition>('bottom-right');3435 return (36 <Toast.Provider position={position}>37 <div className="space-y-4">38 <div className="grid grid-cols-2 gap-2 sm:flex sm:flex-wrap">39 {positions.map((pos) => (40 <Button41 key={pos.value}42 variant={position === pos.value ? 'default' : 'outline'}43 size="sm"44 onClick={() => setPosition(pos.value)}45 >46 {pos.label}47 </Button>48 ))}49 </div>50 <PositionsInner />51 </div>52 </Toast.Provider>53 );54}
API Reference
Toast.Provider
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | — | The app content. |
maxToasts | number | 5 | Maximum number of visible toasts. |
position | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "bottom-right" | Where toasts appear on screen. |
useToast()
Returns an object with:
| Method | Type | Description |
|---|---|---|
toast | (options: ToastOptions) => string | Shows a toast, returns its ID. |
dismiss | (id: string) => void | Dismisses a toast by ID. |
ToastOptions
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Toast title (required). |
description | string | — | Optional description text. |
variant | "default" | "success" | "error" | "info" | "warning" | "default" | Visual variant. |
duration | number | 5000 | Auto-dismiss delay in ms. Set 0 for no auto-dismiss. |
action | { label: string; onClick: () => void } | — | Optional action button. |