Keyframery

Toast

Toasts slide in and stack, the ones behind shrink back, and they spread out when you hover.

See it as an AI agent does.

Resize preview. Focus the handle and use the left or right arrow keys. Hold Shift for larger steps.— px
Customize1 controls
Animation speed1×

Installation

npx shadcn@latest add @keyframery/toast

This adds components/keyframery/toast.tsx and its primitive to your project, and installs UI SDK. The motion tokens are added to your global CSS the first time you install a component.

Usage

import { toast, ToastRegion } from "@/components/keyframery/toast"

// Once, near the root of your app:
export function App() {
  return <ToastRegion />
}

// Anywhere:
export default function Usage() {
  return <button onClick={() => toast("Saved")}>Save</button>
}

Examples

Types

toast.success, toast.error and plain toast. Each gets its own mark, drawn as it arrives.

With an undo

Give it an action for one quick follow-up, like undo. Hovering the stack pauses every toast's timer.

While something runs

toast.promise shows a loading toast, then turns it into success or error when the promise settles.

Motion

MoveWhat you see
SpringA toast arrives from the edge on a spring.
DrawIts icon draws itself.
SpringToasts behind shrink back into a stack and spread out when you hover.

Timing and springiness follow the motion style you set. To change how fast this toast moves, pass speed:

<ToastRegion speed="fast" />

"fast" is 0.6×, "slow" 1.4×, and a number sets the multiplier. With reduced motion turned on, nothing moves: changes happen at once or with a short fade.

Theming

Set these CSS variables on the component or a parent. Leave them unset to follow the light and dark theme. The open Customize panel below the preview lets you try these settings.

VariableWhat it changesDefault
--toast-faceToast sheet and action surfaces--popover; --background on action; --accent on action in dark
--toast-inkTitle and description text--foreground; --muted-foreground for description; --popover-foreground on sheet
--toast-accentStatus icon coloursuccess green; --destructive for error; --foreground for info/warning
--toast-radiusToast corners14px
--toast-paddingToast padding0.75rem
--toast-gapSpace between toast contents0.75rem
--toast-widthRegion width360px
--toast-action-heightAction button height1.75rem

API reference

Every part takes className and children. Parts from UI SDK also take render, to draw your own element, and a function of their state for className and style. Props not listed here are in the UI SDK toast reference.

ToastAction

Renders a <button>, and takes its props too.

Prop

Type

ToastClose

Renders a <button>, and takes its props too.

Prop

Type

ToastIcon

Renders a <span>, and takes its props too.

Prop

Type

ToastRegion

Renders a <element>, and takes its props too.

Prop

Type

Other parts

These take the props of the element they render, and nothing else:

  • Toast: a <li>
  • ToastDescription: a <div>
  • ToastTitle: a <div>

Keyboard

KeyWhat it does
F6Moves focus to the toasts.
TabMoves between a toast's buttons.
EscapeDismisses the focused toast.

Accessibility

Keyboard, focus and screen-reader behaviour come from UI SDK and are not changed. More in Accessibility.

Swap the import

Already using UI SDK's toast with your own styles? Keep your markup and change one line. The primitive adds motion and nothing else.

// Before
import { … } from "@ui-sdk/react/toast"

// After: same parts, same props, now animated
import { … } from "@/components/keyframery/primitives/toast"

Questions

How does the animated Toast for UI SDK move?

Spring: A toast arrives from the edge on a spring. Draw: Its icon draws itself. Spring: Toasts behind shrink back into a stack and spread out when you hover.

Do I need Motion or Framer Motion for the animated Toast?

No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.

Can I keep my own styling and only take the motion?

Yes. Import from @/components/keyframery/primitives/toast instead. It has the same parts and props as @ui-sdk/react/toast and adds motion only.

What happens to the Toast when someone turns on reduced motion?

Nothing moves. State changes happen at once, or with a short fade.

All components

On this page