||

Toast

Documentation Index

Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.

Generates standard and gooey toast notifications.

doc
toast-demo

Overview

Use Toast for short feedback that appears after an action.

Toasts are useful for saves, copies, uploads, background tasks, and lightweight errors. They should not contain information the user must act on later.

Honest UI includes two toast styles:

  • Toast: a standard, quiet notification built on Base UI.
  • Gooey Toast: an animated notification with morphing transitions and more expressive motion.

Anatomy

A toast has a title or message, optional description, status, optional action, and duration. A provider or toaster renders the stack of active toasts.

Behavior

Use status to match the result. Use promise helpers when an async action has loading, success, and error states.

Use the standard Toast when the interface should feel calm and utilitarian. Use Gooey Toast when the notification is part of a more animated product moment, such as uploads, saves, confirmations, and async progress.

Accessibility

Keep messages short and clear. Important errors should also appear near the affected form or content, not only in a toast.

Installation

 
npx honestui@latest add toast
Add the ToastProvider to your app.
import { ToastProvider } from "@/components/ui/toast"

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head />
      <body>
        <ToastProvider>
          <main>{children}</main>
        </ToastProvider>
      </body>
    </html>
  )
}

Usage

 
import { toastManager } from "@/components/ui/toast"
toastManager.add({
  title: "Event has been created",
  description: "Monday, January 3rd at 6:00pm",
})

By default, toasts appear in the bottom-right corner. You can change this by setting the position prop on the ToastProvider.

Allowed values: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. For example:

<ToastProvider position="top-center">{children}</ToastProvider>

Use the variant option to show the animated gooey variation from the same toast API:

toastManager.add({
  variant: "gooey",
  title: "Event has been created",
  description: "Monday, January 3rd at 6:00pm",
})

You can combine variant: "gooey" with status types, actions, position, duration, and promise helpers.

toastManager.add({
  variant: "gooey",
  type: "success",
  title: "Saved",
  description: "Your changes are live.",
  position: "top-right",
})

Standard Toast Examples

Our examples cover status, loading, actions, promise state, and varied toast heights.

With Status

toast-with-status

Loading

toast-loading

With Action

toast-with-action

Promise

toast-promise

With Varying Heights

toast-heights

Gooey Toast Usage

Gooey Toast is a variation of the Toast component. You do not install or render a separate provider.

By default, standard toasts appear in the bottom-right corner. Gooey toasts appear in the top-right corner unless you pass a position option.

Allowed values: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right.

toastManager.add({
  variant: "gooey",
  position: "bottom-center",
  title: "Synced",
  description: "All records are up to date.",
})

Gooey Toast Examples

Our examples cover the animated toast style, state variants, promise handling, action buttons, and placement.

Basic Gooey Toast

gooey-toast-demo

Gooey States

Gooey Toast supports success, error, warning, info, and action states.

gooey-toast-states

Gooey Promise

Drive gooey toast states from promises for async operations.

gooey-toast-promise

Gooey With Action Button

Add an interactive button to a gooey toast.

gooey-toast-with-button

Gooey Position

Control where gooey toasts appear on the screen.

gooey-toast-position

Gooey Toast API Reference

toastManager.add

The same toastManager.add method shows both standard and gooey toasts.

Use no variant for a standard toast:

toastManager.add({
  title: "Saved",
  description: "Your changes are live.",
})

Use variant: "gooey" for the animated variation:

toastManager.add({
  variant: "gooey",
  type: "success",
  title: "Saved",
  description: "Your changes are live.",
})

Gooey Options

interface GooeyOptions {
  variant?: "gooey"
  title?: string
  description?: ReactNode | string
  position?: GooeyPosition
  duration?: number | null
  icon?: ReactNode | null
  styles?: GooeyStyles
  fill?: string
  roundness?: number
  autopilot?: boolean | { expand?: number; collapse?: number }
  button?: {
    title: string
    onClick: () => void
  }
}

Toast Provider Props

interface ToastProviderProps {
  position?: ToastPosition // Standard toast position
  gooeyPosition?: ToastPosition // Default position for gooey toasts
  gooeyOptions?: Partial<GooeyOptions>
}