Skip to content

You're reading the docs for qwik-sonner 1.0.3, the Qwik 1 (@builder.io/qwik) line. It no longer receives new features.Docs for 1.0.3 (Qwik 1)

Go to the Qwik 2 docs (v2)Qwik 2 docs
API reference

API reference

Everything exported by qwik-sonner 1.x: Toaster, toast and the Toast, ExternalToast and ToasterProps types.

toast()

toast(message, options?)            // message: string | JSXOutput
toast.message(message, options?)
toast.success(message, options?)
toast.info(message, options?)
toast.warning(message, options?)
toast.error(message, options?)
toast.loading(message, options?)
toast.promise(promise, data)
toast.custom((id) => jsx, options?)
toast.dismiss(id?)

Action

import { $ } from "@builder.io/qwik";

toast("Event has been created", {
  action: {
    label: "Undo",
    onClick$: $(() => console.log("Undo")),
  },
});

Promise

import { $ } from "@builder.io/qwik";

toast.promise(() => new Promise((resolve) => setTimeout(resolve, 2000)), {
  loading: "Loading…",
  success: $((data) => `${data.name} has been added!`),
  error: "Error",
});
FieldTypeDefault
loadingstring—
Loading message.
successstring | JSXOutput | QRL<(data) => …>—
Shown on resolve.
errorstring | JSXOutput | QRL<(error) => …>—
Shown on reject.
descriptionstring | JSXOutput | QRL<(data) => …>—
Description of the settled toast.
finally() => void | Promise<void>—
Runs when the promise settles.

Custom JSX

// Custom JSX with the default styling
toast(<div>My custom toast</div>);

// Fully custom, unstyled
toast.custom((id) => (
  <div>
    <h1>Custom toast</h1>
    <button onClick$={() => toast.dismiss(id)}>Dismiss</button>
  </div>
));

Updating and dismissing

const toastId = toast("Sonner");

toast.success("Toast has been updated", { id: toastId });

toast.dismiss(toastId); // one toast
toast.dismiss();        // all toasts

Callbacks

toast("Event has been created", {
  onDismiss$: $((t) => console.log(`Toast ${t.id} has been dismissed`)),
  onAutoClose$: $((t) => console.log(`Toast ${t.id} has been closed automatically`)),
});

Toaster props

PropTypeDefault
positionPosition"bottom-right"
Corner the toasts stack in.
theme"light" | "dark" | "system""light"
Color scheme.
richColorsbooleanfalse
Colored success/error/info/warning toasts.
invertboolean | Signal<boolean>false
Invert toast colors.
expandbooleanfalse
Expand all toasts.
visibleToastsnumber3
Toasts visible at once.
closeButtonbooleanfalse
Close button on every toast.
durationnumber4000
Default duration in ms.
gapnumber14
Gap between expanded toasts (px).
offsetstring | number"32px"
Distance from the viewport edges.
dir"rtl" | "ltr" | "auto""auto"
Text direction.
hotkeystring[]["altKey", "KeyT"]
Keys that focus the toasts.
toastOptionsToastOptions—
Defaults for every toast: class, descriptionClass, style, actionButtonStyle, cancelButtonStyle, duration, unstyled, classes, closeButton.
iconsToastIcons—
Components for success, info, warning, error, loading.
containerAriaLabelstring"Notifications"
Label of the toasts region.
pauseWhenPageIsHiddenboolean—
Pause timers while the tab is hidden.
class / stylestring / CSSProperties—
Applied to the toast list.
loadingIconDeprecatedComponent—
Use icons.loading.

Toast options

OptionTypeDefault
idstring | number—
Reuse to update an existing toast.
descriptionstring | JSXOutput—
Second line. Strings are parsed as sanitized HTML.
durationnumber4000
Use Number.POSITIVE_INFINITY to persist.
iconComponent—
Custom icon component.
action / cancelAction | JSXOutput—
{ label, onClick$, preventDefault? } or JSX.
closeButtonboolean—
Override the Toaster's close button.
dismissiblebooleantrue
Allow swiping / closing.
importantboolean—
Announce with aria-live="assertive".
positionPosition—
Override the Toaster position.
invertboolean—
Invert this toast's colors.
onDismiss$QRL<(toast) => unknown>—
Close button clicked or toast swiped.
onAutoClose$QRL<(toast) => unknown>—
Timer ran out.
unstyledboolean—
Drop the default styles.
class / descriptionClass / classesstring / string / ToastClassnames—
Classes for the toast and its parts.
style / actionButtonStyle / cancelButtonStyleCSSProperties—
Inline styles.