Toast

A brief, dismissible notification that stacks in a corner of the screen.

Usage

import { ToastProvider, Toaster, useToastManager } from '@appica/ui-react/toast'

Mount ToastProvider near the root of your app and render Toaster once inside it — that's the portal-anchored viewport every toast appears in. Then call useToastManager().add(...) from anywhere below the provider to fire one.

function App() {
  return (
    <ToastProvider>
      <YourApp />
      <Toaster />
    </ToastProvider>
  )
}

function SaveButton() {
  const toast = useToastManager()
  return <Button onClick={() => toast.add({ title: 'Changes saved' })}>Save</Button>
}

A toast is imperative: you describe it as data (title, description, an optional icon, an action button) and the Toaster renders, stacks, and animates it for you. Each one auto-dismisses after timeout (5s by default), can be swiped away, and exposes a close button. Toaster accepts a position to pin the stack to any corner or edge.

In the examples below, triggers fire real toasts that appear in their fixed corner of the page — scroll up if you don't see one land.

Examples

Default

Fire a toast with a title and description from a useToastManager().add(...) call. It slides in, waits, and dismisses itself.

'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager()
  return (
    <Button
      onClick={() =>
        toast.add({
          title: 'Changes saved',
          description: 'Your preferences have been updated.',
        })
      }
    >
      Show toast
    </Button>
  )
}

export default function ToastDefault() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}

With an icon

Pass a leading icon through the toast's typed data (useToastManager<{ icon?: ReactNode }>()). A filled, color-matched glyph signals success, error, or another state at a glance while the surface stays neutral.

'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { CircleCheckFilled, CircleXFilled, AlertTriangleFilled, InfoCircleFilled } from '@appica/icons-react'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager<{ icon?: React.ReactNode }>()
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Payment received',
            description: 'Invoice #1024 has been settled.',
            data: { icon: <CircleCheckFilled className="text-success-emphasis" /> },
          })
        }
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Upload failed',
            description: 'The file exceeds the 25 MB limit.',
            data: { icon: <CircleXFilled className="text-error-emphasis" /> },
          })
        }
      >
        Error
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Storage almost full',
            description: 'You have used 92% of your quota.',
            data: { icon: <AlertTriangleFilled className="text-warning-emphasis" /> },
          })
        }
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Heads up',
            description: 'Maintenance is scheduled for Sunday.',
            data: { icon: <InfoCircleFilled className="text-info-emphasis" /> },
          })
        }
      >
        Info
      </Button>
    </div>
  )
}

export default function ToastIconExample() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}

With a thumbnail

For more prominence, wrap the icon in a Thumbnail (size="sm") with an icon-* variant — a tinted badge that pairs a soft background with the state color.

'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Button } from '@appica/ui-react/button'
import { Bell, CircleCheck, CircleX } from '@appica/icons-react'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager<{ icon?: React.ReactNode }>()
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'New notification',
            description: 'You have 3 unread messages.',
            data: {
              icon: (
                <Thumbnail variant="icon-soft" size="sm">
                  <Bell />
                </Thumbnail>
              ),
            },
          })
        }
      >
        Default
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Payment received',
            description: 'Invoice #1024 has been settled.',
            data: {
              icon: (
                <Thumbnail variant="icon-success" size="sm">
                  <CircleCheck />
                </Thumbnail>
              ),
            },
          })
        }
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Upload failed',
            description: 'The file exceeds the 25 MB limit.',
            data: {
              icon: (
                <Thumbnail variant="icon-error" size="sm">
                  <CircleX />
                </Thumbnail>
              ),
            },
          })
        }
      >
        Error
      </Button>
    </div>
  )
}

export default function ToastThumbnailExample() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}

With an action

Add actionProps for an inline button — an "Undo", "Retry", or "View". Its onClick runs your handler; here it fires a follow-up toast.

'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager()
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast.add({
          title: 'Message archived',
          actionProps: {
            children: 'Undo',
            onClick: () => toast.add({ title: 'Message restored' }),
          },
        })
      }
    >
      Archive message
    </Button>
  )
}

export default function ToastAction() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}

Promise

Hand toast.promise(...) a promise plus loading / success / error states and it swaps the content as the promise settles — ideal for saves and uploads. (This demo fails at random to show both outcomes.)

'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { CircleCheck, CircleX } from '@appica/icons-react'
import { ToastSandbox } from './sandbox'

function save() {
  return new Promise<{ name: string }>((resolve, reject) => {
    setTimeout(() => (Math.random() > 0.3 ? resolve({ name: 'report.pdf' }) : reject(new Error('Network error'))), 2000)
  })
}

function Demo() {
  const toast = useToastManager<{ icon?: React.ReactNode }>()
  return (
    <Button
      onClick={() =>
        toast.promise(save(), {
          loading: {
            title: 'Saving…',
            data: {
              icon: (
                <Thumbnail variant="icon-soft" size="sm">
                  <Spinner currentColor className="text-base" />
                </Thumbnail>
              ),
            },
          },
          success: {
            title: 'Saved',
            description: 'report.pdf is ready to share.',
            data: {
              icon: (
                <Thumbnail variant="icon-success" size="sm">
                  <CircleCheck />
                </Thumbnail>
              ),
            },
          },
          error: {
            title: 'Could not save',
            description: 'Check your connection and try again.',
            data: {
              icon: (
                <Thumbnail variant="icon-error" size="sm">
                  <CircleX />
                </Thumbnail>
              ),
            },
          },
        })
      }
    >
      Save document
    </Button>
  )
}

export default function ToastPromise() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}

Positions

Set position on Toaster to anchor the stack: any of the six corners and edges. Toasts swipe toward their nearest edge to dismiss.

'use client'

import * as React from 'react'
import { ToastProvider, Toaster, useToastManager, type ToastPosition } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'

const POSITIONS: ToastPosition[] = [
  'top-left',
  'top-center',
  'top-right',
  'bottom-left',
  'bottom-center',
  'bottom-right',
]

function Picker({ onPosition }: { onPosition: (position: ToastPosition) => void }) {
  const toast = useToastManager()
  const show = (position: ToastPosition) => {
    onPosition(position)
    toast.add({ title: 'Notification', description: `Anchored ${position}.` })
  }
  return (
    <div className="grid grid-cols-3 gap-2">
      {POSITIONS.map((position) => (
        <Button key={position} variant="outline" size="sm" onClick={() => show(position)}>
          {position}
        </Button>
      ))}
    </div>
  )
}

export default function ToastPositions() {
  const [position, setPosition] = React.useState<ToastPosition>('bottom-right')
  return (
    <ToastProvider>
      <Picker onPosition={setPosition} />
      <Toaster position={position} />
    </ToastProvider>
  )
}

Timeout & progress

timeout controls how long a toast lingers — pass timeout: 0 for a sticky toast that stays until dismissed. Progress is opt-in: set progress on the Toaster to draw a thin bar counting down on any auto-dismissing toast (including ones that use the default 5s). When you do, set timeout on the Toaster to match a custom ToastProvider timeout so the bar's duration lines up.

'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager()
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Auto-dismiss',
            description: 'This toast closes in 6 seconds.',
            timeout: 6000,
          })
        }
      >
        Timed (6s)
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Stays put',
            description: 'Set timeout to 0 to keep a toast until dismissed.',
            timeout: 0,
          })
        }
      >
        Persistent
      </Button>
    </div>
  )
}

export default function ToastTimeout() {
  return (
    <ToastSandbox progress>
      <Demo />
    </ToastSandbox>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

Under RTL the toast's layout mirrors — the icon leads from the right, the close button moves to the left — and the countdown progress bar drains in the reading direction. For setup details and caveats, see the RTL guide.

API reference

Toast wraps Base UI's Toast. Each part forwards its remaining props to the matching Base UI primitive and carries a data-slot for styling — the tables below list the Appica additions and the most common props.

ToastProvider

Holds the toast queue and timing config. Wrap your app (or the subtree that fires toasts) in it. Renders no DOM of its own.

Prop	Type	Default	Description
`timeout`	`number`	`5000`	Default auto-dismiss delay (ms) for toasts that don't set their own.
`limit`	`number`	`3`	Maximum toasts shown at once; the rest queue and surface as room frees up.
`toastManager`	`ToastManager`	—	A manager from `createToastManager()` to drive toasts from outside React.
`children`	`ReactNode`	—	Your app subtree.

Toaster

The viewport: portals to the body and renders the live stack. Render exactly one per provider.

Prop	Type	Default	Description
`position`	`'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	`'bottom-right'`	Where the stack is anchored; also sets the default swipe-to-dismiss directions.
`progress`	`boolean`	`false`	Opt in to a countdown progress bar on auto-dismissing toasts.
`timeout`	`number`	`5000`	Provider default (ms) used to size the progress bar for toasts that don't set their own `timeout`. Match your `ToastProvider`'s `timeout`.
`container`	`HTMLElement \| Ref \| null`	`document.body`	Portal target — scope the toasts to a specific element.
`portalProps`	`Toast.Portal props`	—	Escape hatch forwarded to the underlying `Toast.Portal`.
`className`	`string \| ((state) => string)`	—	Extra classes on the viewport, merged via `tailwind-merge`.

Toaster reads the live toasts from the manager and renders each as a Toast with its title, description, optional data.icon, and actionProps.

useToastManager

A hook returning the manager used to create and control toasts. Must be called under a ToastProvider.

Method	Signature	Description
`add`	`(options) => string`	Show a toast; returns its id.
`update`	`(id, options) => void`	Patch an existing toast in place.
`close`	`(id) => void`	Dismiss a toast by id.
`promise`	`(promise, states) => Promise`	Drive a toast through `loading` / `success` / `error` states.
`toasts`	`ToastObject[]`	The current live toasts (consumed by `Toaster`).

createToastManager() returns the same control surface (minus the reactive toasts) for firing toasts outside the React tree — pass it to ToastProvider's toastManager.

`add` / `update` options

Option	Type	Default	Description
`title`	`string`	—	The toast heading.
`description`	`string`	—	Supporting body text.
`timeout`	`number`	`5000`	Auto-dismiss delay (ms). `0` keeps it until dismissed.
`type`	`string`	—	A free-form category, also surfaced as `data-type` for styling.
`priority`	`'low' \| 'high'`	`'low'`	`'high'` interrupts screen readers (use for errors).
`data`	`T`	—	Your typed payload — the `Toaster` reads `data.icon` for the leading icon.
`actionProps`	`button props`	—	Renders an inline action button (`children`, `onClick`, …).
`onClose`	`() => void`	—	Fired when the toast is removed.

Toast and its parts

Toaster assembles these for you, but they're exported for manual composition (custom layouts, extra parts): Toast, ToastIcon, ToastTitle, ToastDescription, ToastActions, ToastAction, ToastClose, ToastProgress, and the lower-level ToastViewport / ToastPortal.

Prop	Component	Type	Default	Description
`toast`	`Toast`	`ToastObject`	—	Required. The toast data from `toasts`.
`position`	`Toast`	`ToastPosition`	inherited	Override the anchor/animation for a single toast.
`dismissible`	`Toast`	`boolean`	`true`	Render the close button.
`progress`	`Toast`	`boolean`	`false`	Show the countdown progress bar (when `timeout > 0`).
`swipeDirection`	`Toast`	`axis \| axis[]`	by position	Allowed swipe-to-dismiss directions.
`closeLabel`	`Toast` / `ToastClose`	`string`	`'Dismiss'`	Accessible label for the close button.
`variant` / `size`	`ToastAction`	`buttonVariants`	`primary` / `sm`	Styles the action button like a `Button`.

Accessibility

The Toaster viewport is a labelled landmark (an aria-live region); press F6 to jump to it from anywhere on the page.
New toasts are announced politely by default. Set priority: 'high' on important ones (errors, warnings) to interrupt and announce immediately.
The close button carries an accessible label (closeLabel, default "Dismiss"); it's hidden from the a11y tree until the stack is hovered or focused, then revealed.
Keep toast text short and self-contained — they disappear, so don't put the only copy of critical information in one.
All enter/exit, stacking, and swipe animations honour prefers-reduced-motion, and the countdown progress bar is hidden under reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Toast

Usage

Examples

Default

With an icon

With a thumbnail

With an action

Promise

Positions

Timeout & progress

RTL

API reference

ToastProvider

Toaster

useToastManager

`add` / `update` options

Toast and its parts

Accessibility

Toast

Usage

Examples

Default

With an icon

With a thumbnail

With an action

Promise

Positions

Timeout & progress

RTL

API reference

ToastProvider

Toaster

useToastManager

add / update options

Toast and its parts

Accessibility

`add` / `update` options