Documentation

Everything you need to use bong-toast in your project.

Installation

Install bong-toast via the shadcn CLI:

npx shadcn@latest add https://bong-toast.vercel.app/r/bong-toast.json

This will add the BongToast component and useBongToast hook to your project.

Quick Start

Add <BongToast /> to your layout or root component, then use the hook anywhere to trigger toasts.

// app/layout.tsx or root component
import { BongToast } from "@/components/bong-toast/bong-toast";

export default function Layout({ children }) {
  return (
    <>
      {children}
      <BongToast position="bottom-right" />
    </>
  );
}

// Any component
import { useBongToast } from "@/components/bong-toast/use-bong-toast";

function MyComponent() {
  const { toast } = useBongToast();

  return (
    <button onClick={() => toast({ title: "Hello!", variant: "success" })}>
      Show toast
    </button>
  );
}

BongToast Props

Props for the <BongToast /> provider component.

Prop	Type	Default	Description
position	ToastPosition	"bottom-right"	Where toasts appear on screen
maxVisible	number	5	Maximum number of visible toasts
size	ToastSize	"md"	Default size for all toasts: "sm" \| "md" \| "lg"
duration	number	4000	Default auto-dismiss duration in ms
spring	ToastSpring	—	Default spring animation config
style	ToastStyle	—	Default custom style for all toasts

useBongToast Hook

The hook returns the following:

Return	Type	Description
toast	(options: ToastOptions) => string	Show a toast, returns its ID
dismiss	(id: string) => void	Dismiss a specific toast by ID
clear	() => void	Dismiss all active toasts
toasts	ToastData[]	Current list of active toasts

You can also use toast() and dismissToast() imperatively outside React components:

import { toast, dismissToast } from "@/components/bong-toast/use-bong-toast";

// Works outside React components
toast({ title: "Imperative toast!", variant: "info" });

Toast Options

Options passed to toast() when triggering a notification.

Option	Type	Default	Description
title	string	—	Toast title (required)
description	string	—	Expandable description shown on hover
variant	ToastVariant	"default"	"default" \| "success" \| "error" \| "warning" \| "info"
duration	number	4000	Auto-dismiss time in ms (overrides global)
size	ToastSize	"md"	Toast size (overrides global)
style	ToastStyle	—	Custom style (overrides global)
spring	ToastSpring	—	Spring config (overrides global)

Styling

Customize toast appearance with the ToastStyle type:

interface ToastStyle {
  bg?: string;          // Background color (any CSS color)
  fg?: string;          // Text color
  borderColor?: string; // Border color
  borderRadius?: number; // Border radius in px
}

Styles can be set globally on the <BongToast /> component or per-toast. Per-toast styles are merged with (and override) global styles.

// Global style
<BongToast style={{ borderRadius: 20 }} />

// Per-toast override
toast({
  title: "Custom",
  style: {
    bg: "#1a1a2e",
    fg: "#e9d5ff",
    borderColor: "#7c3aed",
    borderRadius: 24,
  },
});

Spring Config

Control the spring animation with ToastSpring:

interface ToastSpring {
  stiffness?: number; // Default: 400 — higher = faster snap
  damping?: number;   // Default: 25  — higher = less bounce
  mass?: number;      // Default: 0.8 — higher = heavier/slower
}

Some preset combinations:

Snappy

{ stiffness: 500, damping: 30, mass: 0.5 }

Bouncy

{ stiffness: 300, damping: 12, mass: 1 }

Smooth

{ stiffness: 200, damping: 20, mass: 1.5 }