@opentui-ui/toast

A beautiful toast library for terminal UIs built on OpenTUI

_{Built by Matt Simpson | Inspired by Sonner}

Installation

bun add @opentui-ui/toast

Quick Start

import { toast, ToasterRenderable } from "@opentui-ui/toast";

// 1. Add the toaster to your app (one line!)
ctx.root.add(new ToasterRenderable(ctx));

// 2. Show toasts from anywhere!
toast("Hello World");

That's it! No providers, no context, no configuration required.

Quick Reference

// Toast Types
toast("message");           // default
toast.success("message");   // green checkmark
toast.error("message");     // red X
toast.warning("message");   // yellow warning
toast.info("message");      // blue info
toast.loading("message");   // animated spinner

// Common Patterns
toast("msg", { description: "details" }); // Two-line toast
toast("msg", { duration: Infinity });     // Persistent (manual dismiss)
toast("msg", { action: { label: "Undo", onClick: fn } }); // With button

// Dismiss
const id = toast("Hello");
toast.dismiss(id);  // Dismiss one
toast.dismiss();    // Dismiss all

// Update existing toast
const id = toast.loading("Uploading...");
toast.success("Done!", { id }); // Updates in place

Toast Types

toast("Default notification");
toast.success("Operation completed!");
toast.error("Something went wrong");
toast.warning("Please check your input");
toast.info("Did you know?");
toast.loading("Processing...");

With Descriptions

toast.success("File uploaded", {
  description: "Your file has been saved to the cloud",
});

Promise Toast

The toast.promise() API automatically shows loading, success, and error states:

toast.promise(fetchData(), {
  loading: "Fetching data...",
  success: "Data loaded successfully!",
  error: "Failed to load data",
});

// With dynamic messages
toast.promise(saveUser(data), {
  loading: "Saving user...",
  success: (user) => `${user.name} has been saved`,
  error: (err) => `Error: ${err.message}`,
});

Actions

Add interactive buttons to your toasts:

toast("File deleted", {
  action: {
    label: "Undo",
    onClick: () => restoreFile(),
  },
});

Updating Toasts

Update an existing toast by passing its ID:

const id = toast.loading("Uploading...");

// Later...
toast.success("Upload complete!", { id });

// Or on error
toast.error("Upload failed", { id });

Dismissing Toasts

// Dismiss a specific toast
const id = toast("Hello");
toast.dismiss(id);

// Dismiss all toasts
toast.dismiss();

Duration

Duration Presets

Use the built-in TOAST_DURATION presets for consistent, readable duration values:

import { toast, TOAST_DURATION } from "@opentui-ui/toast";

// Quick confirmation (2s)
toast.success("Copied!", { duration: TOAST_DURATION.SHORT });

// Standard duration (4s) - this is the default
toast("Hello", { duration: TOAST_DURATION.DEFAULT });

// Important message (6s)
toast.warning("Check your settings", { duration: TOAST_DURATION.LONG });

// Critical information (10s)
toast.error("Connection lost", { duration: TOAST_DURATION.EXTENDED });

// Manual dismiss only
toast.info("Click to continue", { duration: TOAST_DURATION.PERSISTENT });

Duration Preset Values

Preset	Duration	Use Case
SHORT	2000ms	Brief confirmations
DEFAULT	4000ms	Standard notifications
LONG	6000ms	Important messages
EXTENDED	10000ms	Critical information
PERSISTENT	Infinity	Requires manual dismissal

Custom Duration

You can also pass any number in milliseconds:

// Custom duration (in milliseconds)
toast("This disappears in 10 seconds", {
  duration: 10000,
});

// Persistent toast (won't auto-dismiss)
toast("I'll stay until dismissed", {
  duration: Infinity,
});

Themes

Optional theme presets are available via a separate import. These override the built-in defaults with alternative visual styles.

import { ToasterRenderable } from "@opentui-ui/toast";
import { minimal } from "@opentui-ui/toast/themes";

const toaster = new ToasterRenderable(ctx, minimal);

Available Themes

Theme	Description
minimal	Clean and unobtrusive, no borders
monochrome	Grayscale only, no colors

Customizing Themes

Spread a theme and override specific options:

import { minimal } from "@opentui-ui/toast/themes";

const toaster = new ToasterRenderable(ctx, {
  ...minimal,
  position: "bottom-right",
  stackingMode: "stack",
});

Theme Utilities

import { themes } from "@opentui-ui/toast/themes";

// Access all themes
themes.minimal;
themes.monochrome;

Theme Types

import type { ToasterTheme } from "@opentui-ui/toast/themes";

Toaster Configuration

Customize the toaster appearance and behavior:

const toaster = new ToasterRenderable(ctx, {
  // Position on screen
  position: "bottom-right", // 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'

  // Gap between toasts (terminal rows)
  gap: 1,

  // How to handle multiple toasts
  stackingMode: "single", // 'single' | 'stack'

  // Max visible toasts in stack mode
  visibleToasts: 3,

  // Show close button on toasts
  closeButton: false,

  // Maximum width for toasts
  maxWidth: 60,

  // Offset from screen edges
  offset: {
    top: 1,
    right: 2,
    bottom: 1,
    left: 2,
  },

  // Custom icons
  icons: {
    success: "✓",
    error: "✗",
    warning: "⚠",
    info: "ℹ",
    loading: "◌",
    close: "×",
  },

  // Toast styling and duration options
  toastOptions: {
    style: {
      /* base styles */
    },
    duration: 4000,
    success: {
      style: {
        /* overrides */
      },
      duration: 3000,
    },
    // ... other types
  },
});

ToasterOptions Reference

Option	Type	Default	Description
position	Position	"bottom-right"	Position on screen
gap	number	1	Gap between toasts (terminal rows)
stackingMode	StackingMode	"single"	How to handle multiple toasts: "single" or "stack"
visibleToasts	number	3	Max visible toasts in stack mode
closeButton	boolean	false	Show close button on toasts
maxWidth	number	60	Maximum width for toasts (terminal columns)
offset	ToasterOffset	{ top: 1, right: 2, bottom: 1, left: 2 }	Offset from screen edges
icons	Partial<ToastIcons> | false	-	Custom icons for each toast type, or false to disable
toastOptions	ToastOptions	-	Default toast options (styles, duration, per-type overrides)

Styling

Configure toast styles using the toastOptions prop:

const toaster = new ToasterRenderable(ctx, {
  toastOptions: {
    // Base styles applied to all toasts
    style: {
      backgroundColor: "#1a1a1a",
      foregroundColor: "#ffffff",
      borderColor: "#333333",
      borderStyle: "rounded", // 'single' | 'double' | 'rounded' | 'heavy'
      paddingX: 1,
      paddingY: 0,
    },
    // Default duration for all toasts
    duration: 4000,
    // Per-type overrides
    success: {
      style: { borderColor: "#22c55e" },
      duration: 3000,
    },
    error: {
      style: { borderColor: "#ef4444" },
      duration: 6000,
    },
    warning: {
      style: { borderColor: "#f59e0b" },
    },
    info: {
      style: { borderColor: "#3b82f6" },
    },
    loading: {
      style: { borderColor: "#6b7280" },
    },
  },
});

ToastStyle Reference

Property	Type	Default	Description
border	boolean | BorderSides[]	true	Border configuration. true = all sides, false = none, or array like ["left", "right"]
borderColor	string	"#333333"	Border color (hex, rgb, or named)
borderStyle	BorderStyle	"single"	Border style: "single" | "double" | "rounded" | "heavy"
customBorderChars	BorderCharacters	-	Custom border characters (overrides borderStyle)
minHeight	number	3	Minimum height in terminal rows
maxWidth	number	-	Maximum width in terminal columns
minWidth	number	-	Minimum width in terminal columns
padding	number	-	Uniform padding (all sides)
paddingX	number	1	Horizontal padding (left + right)
paddingY	number	0	Vertical padding (top + bottom)
paddingTop	number	-	Top padding
paddingBottom	number	-	Bottom padding
paddingLeft	number	-	Left padding
paddingRight	number	-	Right padding
backgroundColor	string	"#1a1a1a"	Background color
foregroundColor	string	"#ffffff"	Text/foreground color
mutedColor	string	"#6b7280"	Muted text color (for descriptions)
iconColor	string	-	Icon color (defaults to borderColor)

Custom Border Characters

For full control over border rendering, use customBorderChars to define each border character:

const toaster = new ToasterRenderable(ctx, {
  toastOptions: {
    style: {
      border: ["left", "right"],
      customBorderChars: {
        topLeft: "",
        topRight: "",
        bottomLeft: "",
        bottomRight: "",
        horizontal: " ",
        vertical: "┃",
        topT: "",
        bottomT: "",
        leftT: "",
        rightT: "",
        cross: "",
      },
    },
  },
});

This is useful for creating unique border styles, like a vertical bar accent:

// Vertical bar on left and right only
border: ["left", "right"],
customBorderChars: {
  vertical: "┃",
  // Other characters can be empty strings
  topLeft: "", topRight: "", bottomLeft: "", bottomRight: "",
  horizontal: " ", topT: "", bottomT: "", leftT: "", rightT: "", cross: "",
},

Per-Toast Styles

Override styles on individual toasts:

toast.success("Custom styled!", {
  style: {
    borderColor: "#8b5cf6",
    backgroundColor: "#1e1b4b",
  },
});

Icon Sets

Choose from built-in icon sets based on terminal capabilities:

import {
  DEFAULT_ICONS, // Unicode icons (default)
  ASCII_ICONS, // ASCII-only for limited terminals
  MINIMAL_ICONS, // Single character icons
  EMOJI_ICONS, // Emoji icons
} from "@opentui-ui/toast";

// Use ASCII icons for terminals with limited Unicode support
const toaster = new ToasterRenderable(ctx, {
  icons: ASCII_ICONS,
});

// Use emoji icons for terminals with good emoji support
const toaster = new ToasterRenderable(ctx, {
  icons: EMOJI_ICONS,
});

Custom Loading Spinner

The loading icon can be either a static string or an animated spinner configuration:

const toaster = new ToasterRenderable(ctx, {
  icons: {
    // Static loading icon (no animation)
    loading: "...",

    // Or animated spinner
    loading: {
      frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
      interval: 80,
    },
  },
});

Some spinner examples:

// Dots spinner
{ frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"], interval: 80 }

// Circle spinner (default)
{ frames: ["◜", "◠", "◝", "◞", "◡", "◟"], interval: 100 }

// Simple ASCII spinner
{ frames: ["-", "\\", "|", "/"], interval: 100 }

// Bouncing bar
{ frames: ["[    ]", "[=   ]", "[==  ]", "[=== ]", "[ ===]", "[  ==]", "[   =]", "[    ]"], interval: 120 }

Disabling Icons

To disable icons entirely, set icons: false:

const toaster = new ToasterRenderable(ctx, {
  icons: false,
});

Individual toasts can still override this by providing a custom icon:

// Icons are disabled globally, but this toast will show a custom icon
toast.success("Done!", { icon: "✓" });

API Reference

toast(message, options?)

Show a default toast.

toast.success(message, options?)

Show a success toast with a checkmark icon.

toast.error(message, options?)

Show an error toast with an X icon.

toast.warning(message, options?)

Show a warning toast with a warning icon.

toast.info(message, options?)

Show an info toast with an info icon.

toast.loading(message, options?)

Show a loading toast with an animated spinner.

toast.promise(promise, options)

Show a toast that updates based on promise state.

toast.dismiss(id?)

Dismiss a specific toast by ID, or all toasts if no ID provided.

toast.getToasts()

Get all currently active toasts.

toast.getHistory()

Get all toasts ever created (including dismissed).

Toast Options

Option	Type	Default	Description
id	string | number	auto	Unique identifier for the toast
description	string | (() => string)	-	Secondary text below the title
duration	number	4000	Time in ms before auto-dismiss
dismissible	boolean	true	Whether the toast can be dismissed
icon	string	type-based	Custom icon to display
action	{ label, onClick }	-	Action button configuration
closeButton	boolean	false	Show close button
style	ToastStyle	-	Per-toast style overrides
onDismiss	(toast) => void	-	Callback when dismissed
onAutoClose	(toast) => void	-	Callback when auto-closed

Examples

Basic Example

import { createCliRenderer } from "@opentui/core";
import { toast, ToasterRenderable } from "@opentui-ui/toast";

const renderer = await createCliRenderer();

// Add toaster
const toaster = new ToasterRenderable(renderer, {
  position: "bottom-right",
});
renderer.root.add(toaster);

// Show some toasts
toast.success("Application started!");

setTimeout(() => {
  toast.info("Press 'q' to quit");
}, 1000);

Async Operation

async function saveData(data: unknown) {
  toast.promise(
    fetch("/api/save", {
      method: "POST",
      body: JSON.stringify(data),
    }),
    {
      loading: "Saving...",
      success: "Saved!",
      error: "Failed to save",
    }
  );
}

Manual Loading State

async function uploadFile(file: File) {
  const id = toast.loading("Uploading...");

  try {
    const result = await upload(file);
    toast.success(`Uploaded ${result.filename}`, { id });
  } catch (error) {
    toast.error("Upload failed", { id });
  }
}

React

For React applications, use the Toaster component and useToasts hook:

import { Toaster, useToasts, toast } from "@opentui-ui/toast/react";

function App() {
  return (
    <>
      <Toaster position="bottom-right" />
      <MyComponent />
    </>
  );
}

function MyComponent() {
  const { toasts } = useToasts();

  useKeyboard((key) => {
    if (key.name === "1") {
      toast.success("Hello World");
    }
  });

  return (
    <box>
      <text>Active toasts: {toasts.length}</text>
    </box>
  );
}

The useToasts hook provides reactive access to the current toast state, re-rendering your component whenever toasts are added, updated, or dismissed.

Solid

For Solid applications, use the Toaster component and useToasts hook:

import { Toaster, useToasts, toast } from "@opentui-ui/toast/solid";

function App() {
  return (
    <>
      <Toaster position="bottom-right" />
      <MyComponent />
    </>
  );
}

function MyComponent() {
  const toasts = useToasts();

  useKeyboard((key) => {
    if (key.name === "1") {
      toast.success("Hello World");
    }
  });

  return (
    <box>
      <text>Active toasts: {toasts().length}</text>
    </box>
  );
}

The useToasts hook returns a reactive accessor that updates whenever toasts change. Call it as a function (toasts()) to access the current array.

TypeScript

Full TypeScript support with exported types:

import type {
  Action,           // Action button configuration
  ExternalToast,    // Options for toast() calls
  Position,         // Toaster position type
  PromiseData,      // Configuration for toast.promise()
  SpinnerConfig,    // Animated spinner configuration { frames, interval }
  StackingMode,     // Stacking mode ('single' | 'stack')
  ToasterOffset,    // Offset configuration for positioning
  ToasterOptions,   // Configuration for ToasterRenderable
  ToastIcons,       // Custom icon set type
  ToastOptions,     // Default toast options (styles, duration, per-type overrides)
  ToastStyle,       // Per-toast styling options
  ToastType,        // Toast type variants
  TypeToastOptions, // Per-type options (style + duration)
} from "@opentui-ui/toast";

// Border types (for customBorderChars) come from @opentui/core
import type { BorderCharacters, BorderSides, BorderStyle } from "@opentui/core";

// Type guards
import { isAction, isSpinnerConfig } from "@opentui-ui/toast";

Constants

import { TOAST_DURATION } from "@opentui-ui/toast";

// Duration presets
TOAST_DURATION.SHORT;      // 2000ms - brief confirmations
TOAST_DURATION.DEFAULT;    // 4000ms - standard notifications
TOAST_DURATION.LONG;       // 6000ms - important messages
TOAST_DURATION.EXTENDED;   // 10000ms - critical information
TOAST_DURATION.PERSISTENT; // Infinity - manual dismiss only

Acknowledgments

Inspired by Sonner by Emil Kowalski.

License

MIT