Toast

Installation#

npmpnpmyarnbun

npx sugarcoat add toast

Examples#

Basic Structure#

A toast notification with title, description, and close button.

Basic Structure

Toast Variants#

Toasts support different variants for semantic meaning.

Variants

With Action Button#

Toasts can include action buttons for user interaction.

With Action

User Notification Toast#

User Notification

Anatomy#

// App-level setup
<Toast.Provider>
  <App />
  <Toast.Viewport />
</Toast.Provider>
 
// Individual toast structure
<Toast variant="success">
  <Toast.Title>Title</Toast.Title>
  <Toast.Description>Description</Toast.Description>
  <Toast.Action>Action</Toast.Action>
  <Toast.Close />
</Toast>

Usage#

Import

import { Toast } from "@sugarcoat/ui-nxt";
import { useToastManager } from "@base-ui-components/react/toast";

Usage

// 1. Wrap your app with the provider
function App() {
return (
  <Toast.Provider>
    <YourApp />
    <Toast.Viewport />
  </Toast.Provider>
);
}

// 2. Use the hook to show toasts
function YourComponent() {
const toastManager = useToastManager();

const showToast = () => {
  toastManager.add({
    title: 'Success!',
    description: 'Operation completed.',
  });
};

return <Button onClick={showToast}>Show Toast</Button>;
}

Triggering Toasts#

Use the useToastManager hook from Base UI to trigger toasts programmatically:

import { useToastManager } from "@base-ui-components/react/toast";
 
function MyComponent() {
  const toastManager = useToastManager();
 
  // Simple toast
  toastManager.add({
    title: "File uploaded",
    description: "Your file has been uploaded successfully.",
  });
 
  // Toast with variant
  toastManager.add({
    title: "Error",
    description: "Failed to save changes.",
    variant: "error",
  });
 
  // Toast with action
  toastManager.add({
    title: "Message sent",
    action: {
      label: "Undo",
      onClick: () => console.log("Undo clicked"),
    },
  });
 
  // Toast with custom duration
  toastManager.add({
    title: "Quick notification",
    duration: 2000, // 2 seconds
  });
 
  // Persistent toast (no auto-dismiss)
  toastManager.add({
    title: "Important",
    duration: Infinity,
  });
}

Props#

Toast.Provider#

Prop	Type	Default	Description
children	ReactNode	-	App content that can trigger toasts

Toast (Root)#

Prop	Type	Default	Description
variant	"default" \| "success" \| "error" \| "warning" \| "info"	"default"	Visual variant of the toast
css	SystemStyleObject	-	Additional CSS styles using Panda CSS syntax

Toast.Viewport#

Prop	Type	Default	Description
hotkey	string[]	["F8"]	Keyboard shortcut to focus the viewport
css	SystemStyleObject	-	Additional CSS styles using Panda CSS syntax

useToastManager.add() Options#

Prop	Type	Default	Description
title	string	-	Toast title
description	string	-	Toast description
variant	"default" \| "success" \| "error" \| "warning" \| "info"	-	Visual variant
duration	number	5000	Duration in ms (use Infinity for persistent)
action	{ label: string; onClick: () => void }	-	Action button configuration
render	(props: { close: () => void }) => ReactNode	-	Custom render function for full control

Accessibility#

Built on Base UI Toast for robust accessibility
Uses ARIA live regions for screen reader announcements
Toasts are focusable and keyboard navigable
F8 key (configurable) focuses the toast viewport
Escape key dismisses focused toast
Auto-dismiss pauses on hover and focus
Actions are keyboard accessible