Skip to main content

​
Overview

The Toast component displays temporary notification messages. It uses Radix UI Toast primitives and includes a powerful useToast hook for programmatic control.

​
Import

import { useToast } from '@repo/ui/toast'
import { Toaster } from '@repo/ui/toast'

​
Setup

Add the Toaster component to your app root: 
import { Toaster } from '@repo/ui/toast'

function App() {
  return (
    <>
      {/* Your app content */}
      <Toaster />
    </>
  )
}

​
useToast Hook

The primary way to display toast notifications programmatically.

​
Returns

​
toast
function
Function to display a new toast notification. See toast function signature below.
​
toasts
ToasterToast[]
Array of currently active toast notifications.
​
dismiss
(toastId?: string) => void
Function to dismiss a toast. If no ID is provided, dismisses all toasts.

​
toast() Function

Call the toast function to display a notification:
​
title
React.ReactNode
The title of the toast notification.
​
description
React.ReactNode
The description/body content of the toast.
​
variant
'default' | 'success' | 'error' | 'warning' | 'info' | 'info2'
default:"'default'"
The visual style variant of the toast:
  • default: Standard success styling with green theme
  • success: Success message with check icon and green theme
  • error: Error message with warning icon and red theme
  • warning: Warning message with info icon and yellow theme
  • info: Info message with info icon and blue theme
  • info2: Alternative info styling with different blue theme
​
action
ToastActionElement
Optional action button element to display in the toast.
​
duration
number
Duration in milliseconds before the toast auto-dismisses. If not provided, toast persists until manually dismissed.
​
open
boolean
Controlled open state of the toast.
​
onOpenChange
(open: boolean) => void
Callback fired when the open state changes.

​
Return Value

The toast() function returns an object with:
​
id
string
Unique identifier for the toast instance.
​
dismiss
() => void
Function to dismiss this specific toast.
​
update
(props: ToasterToast) => void
Function to update the toast properties after creation.

​
Usage Examples

import { useToast } from '@repo/ui/toast'

function Example() {
  const { toast } = useToast()

  return (
    <button
      onClick={() => {
        toast({
          title: "Success!",
          description: "Your changes have been saved.",
          variant: "success",
        })
      }}
    >
      Save
    </button>
  )
}

// Toast with auto-dismiss
toast({
  title: "Processing...",
  description: "This will close in 3 seconds",
  duration: 3000,
  variant: "info",
})

// Toast with manual control
const { id, dismiss, update } = toast({
  title: "Uploading...",
  description: "0% complete",
})

// Later, update the toast
update({
  title: "Uploading...",
  description: "50% complete",
  id,
})

// Dismiss when done
dismiss()

// Error toast
toast({
  title: "Error",
  description: "Failed to save changes. Please try again.",
  variant: "error",
})

// Warning toast
toast({
  title: "Warning",
  description: "You have unsaved changes.",
  variant: "warning",
})

​
Toast Component

Low-level component for rendering toast notifications. Typically used through the useToast hook.

​
Props

​
title
string
The title text of the toast.
​
description
React.ReactNode | string
The description content of the toast.
​
variant
'default' | 'success' | 'error' | 'warning' | 'info' | 'info2'
default:"'default'"
The visual style variant.
​
className
string
Additional CSS classes to apply.
​
ref
React.Ref<HTMLElement>
Ref to the underlying Radix Toast element.

​
Radix UI Props

Extends React.ComponentPropsWithoutRef<typeof ToastPrimitives.Root>, inheriting Radix Toast props including:
  • open
  • onOpenChange
  • duration
  • type

​
Configuration

​
Toast Limits

const TOAST_LIMIT = 1 // Maximum number of toasts shown at once
Only 1 toast is displayed at a time. New toasts replace older ones.

​
Remove Delay

const TOAST_REMOVE_DELAY = 1000 // Delay before removing dismissed toasts (ms)
Toasts are removed from the DOM 1 second after being dismissed.

​
Accessibility

  • Toasts use Radix UI’s accessible toast primitives
  • Proper ARIA attributes for screen readers
  • Keyboard navigation support
  • Focus management when toasts appear
  • Swipe gestures for mobile dismissal

​
Icon Variants

Each variant displays a corresponding icon:
  • success: Check icon in green container
  • error: Triangle alert icon in red container
  • warning: Info icon in yellow container
  • info: Info icon in blue container
  • info2: Info icon in alternative blue container
  • default: No icon displayed

Build docs developers (and LLMs) love

Get started for freeTalk to us