API Reference

This page provides a detailed reference for all the functions, components, and types exported by svelte-french-toast.

`toast()` Function

The toast function is the primary way to create notifications. It returns the ID of the created toast.

toast(message: Renderable, options?: ToastOptions): string;

Variants

toast.success(message, options): Renders a toast with a success icon.
toast.error(message, options): Renders a toast with an error icon.
toast.loading(message, options): Renders a toast with a loading spinner. The default duration is Infinity.
toast.custom(component, options): Renders a custom Svelte component. See the Usage Guide for an example.

`toast.promise()`

Handles promise lifecycle states automatically.

toast.promise(
    promise: Promise<T>,
    messages: {
        loading: Renderable;
        success: ValueOrFunction<Renderable, T>;
        error: ValueOrFunction<Renderable, any>;
    },
    options?: DefaultToastOptions
): Promise<T>;

Management Functions

toast.dismiss(toastId?: string): Dismisses a specific toast or all toasts if no toastId is provided. The toast will animate out.
toast.remove(toastId?: string): Immediately removes a toast or all toasts without an animation.

Components

`<Toaster />`

The main component that renders toasts. See the Configuration page for all available props.

Other Components

These components are exported for advanced customization, allowing you to build your own ToastBar.

<ToastBar {toast} {position} />: Renders a standard toast UI.
<ToastIcon {toast} />: Renders the icon for a toast.
<ToastMessage {toast} />: Renders the message content of a toast.
<CheckmarkIcon />
<ErrorIcon />
<LoaderIcon />

Types

`ToastOptions`

An object to customize a specific toast.

interface ToastOptions {
  id?: string;
  icon?: Renderable;
  duration?: number;
  ariaProps?: {
    role: 'status' | 'alert';
    'aria-live': 'assertive' | 'off' | 'polite';
  };
  className?: string;
  style?: string;
  position?: ToastPosition;
  iconTheme?: {
    primary: string;
    secondary: string;
  };
  props?: Record<string, any>; // For custom components
}

`ToastPosition`

The position of the toast on the screen.

Values: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right', 'top-start', 'top-end', 'bottom-start', 'bottom-end'. Logical positions (start/end) are recommended for better LTR/RTL support.

`Toast`

The internal representation of a toast object.

interface Toast {
  type: 'success' | 'error' | 'loading' | 'blank' | 'custom';
  id: string;
  message: Renderable;
  // ... and other properties
}

Headless Hooks

For building a completely custom UI from scratch.

useToaster(options): A hook that provides the list of toasts and handlers for managing them.
useToasterStore(options): Provides access to the raw Svelte stores for toasts and pausedAt.

API Reference

toast() Function