Reference

TypeScript reference

Every public type, callback shape, and constant exported by @samline/notify.

All names on this page are valid root exports. RenderableOrFactory and ToastToDismiss can be imported directly from @samline/notify.

import type {
  CustomContent,
  Direction,
  NotifyApi,
  Offset,
  Position,
  PromiseData,
  PromiseExtendedResult,
  PromiseInput,
  PromiseValue,
  Renderable,
  RenderableOrFactory,
  SwipeDirection,
  Theme,
  ToastAction,
  ToastApi,
  ToastId,
  ToastInput,
  ToastOptions,
  ToastSubscriber,
  ToastT,
  ToastToDismiss,
  ToastType,
  ToasterController,
  ToasterOptions,
} from '@samline/notify'

Toast primitives

type ToastId = number | string

type ToastType =
  'normal' | 'action' | 'success' | 'info' | 'warning' | 'error' | 'loading' | 'default'

type Renderable = string | number | boolean | null | undefined
type RenderableOrFactory = Renderable | (() => Renderable)
type CustomContent = HTMLElement | ((container: HTMLElement) => void)

false, null, and undefined render no text; true renders "true". Renderable is text-oriented and does not include JSX or DOM nodes. Use CustomContent for owned DOM. The default and action types use the normal visual treatment unless your CSS differentiates them.

interface ToastAction {
  label: Renderable
  onClick?: (event: Event) => void
  closeOnClick?: boolean
}

closeOnClick defaults to true.

Toast options and records

interface ToastOptions {
  id?: ToastId
  toasterId?: string
  description?: RenderableOrFactory
  type?: ToastType
  richColors?: boolean
  invert?: boolean
  unstyled?: boolean
  closeButton?: boolean
  dismissible?: boolean
  duration?: number
  className?: string
  descriptionClassName?: string
  action?: ToastAction
  cancel?: ToastAction
  testId?: string
  onDismiss?: (toast: ToastT) => void
  onAutoClose?: (toast: ToastT) => void
  onClick?: (event: Event) => void
}

See Configuration for defaults and interactions.

interface ToastT {
  id: ToastId
  toasterId?: string
  title?: RenderableOrFactory
  description?: RenderableOrFactory
  type?: ToastType
  richColors?: boolean
  invert?: boolean
  unstyled?: boolean
  closeButton?: boolean
  dismissible?: boolean
  duration?: number
  className?: string
  descriptionClassName?: string
  position?: Position
  testId?: string
  action?: ToastAction
  cancel?: ToastAction
  custom?: CustomContent
  promise?: PromiseInput<unknown>
  delete?: boolean
  onDismiss?: (toast: ToastT) => void
  onAutoClose?: (toast: ToastT) => void
  onClick?: (event: Event) => void
}

interface ToastToDismiss {
  id: ToastId
  dismiss: boolean
}

ToastT is the state and snapshot shape returned by getToasts() and getHistory(). ToastToDismiss is the event shape sent to low-level subscribers.

The delete field is a legacy record field; current dismissal tracking uses the separate dismissed-id set. Most consumers should not read it; use toast.getToasts(), which filters on the dismissed set, instead.

Toast API

interface ToastApi {
  (message: RenderableOrFactory, options?: ToastOptions): ToastId
  success(message: RenderableOrFactory, options?: ToastOptions): ToastId
  error(message: RenderableOrFactory, options?: ToastOptions): ToastId
  info(message: RenderableOrFactory, options?: ToastOptions): ToastId
  warning(message: RenderableOrFactory, options?: ToastOptions): ToastId
  loading(message: RenderableOrFactory, options?: ToastOptions): ToastId
  message(message: RenderableOrFactory, options?: ToastOptions): ToastId
  custom: (content: CustomContent, options?: ToastOptions) => ToastId
  promise: <Data>(
    input: PromiseInput<Data>,
    data?: PromiseData<Data>
  ) =>
    { id: ToastId; unwrap: () => Promise<Data> } | { id?: undefined; unwrap: () => Promise<Data> }
  dismiss(id?: ToastId): ToastId | undefined
  getHistory(): ToastT[]
  getToasts(): ToastT[]
}

Toaster types

type Position =
  'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center'

type Theme = 'light' | 'dark' | 'system'
type Direction = 'rtl' | 'ltr' | 'auto'
type SwipeDirection = 'top' | 'right' | 'bottom' | 'left'

type Offset =
  | number
  | string
  | {
      top?: number | string
      right?: number | string
      bottom?: number | string
      left?: number | string
    }
interface ToasterOptions {
  id?: string
  theme?: Theme
  position?: Position
  expand?: boolean
  duration?: number
  gap?: number
  visibleToasts?: number
  closeButton?: boolean
  className?: string
  offset?: Offset
  mobileOffset?: Offset
  dir?: Direction
  richColors?: boolean
  invert?: boolean
  unstyled?: boolean
  customAriaLabel?: string
  containerAriaLabel?: string
  closeButtonAriaLabel?: string
  style?: Record<string, string>
  hotkey?: string[]
}

interface ToasterController {
  element: HTMLElement
  options: ToasterOptions
  update: (options?: ToasterOptions) => ToasterController
  destroy: () => void
}

Toaster is a runtime alias of createToaster. There is no separate Toaster type and no framework component.

Promise types

type PromiseInput<Data = unknown> = Promise<Data> | (() => Promise<Data>)

interface PromiseExtendedResult extends ToastOptions {
  message: Renderable
}

type PromiseValue<Data = unknown> =
  | Renderable
  | PromiseExtendedResult
  | ((
      data: Data
    ) => Renderable | PromiseExtendedResult | Promise<Renderable | PromiseExtendedResult>)

interface PromiseData<Data = unknown> extends Omit<ToastOptions, 'description'> {
  loading?: Renderable
  success?: PromiseValue<Data>
  error?: PromiseValue
  description?: Renderable | ((data: Data | unknown) => Renderable | Promise<Renderable>)
  finally?: () => void | Promise<void>
}

See the Promise API for the non-obvious id, description, HTTP, and unwrap() behavior.

Advanced state types

interface ToastInput extends Omit<ToastOptions, 'description'> {
  message?: RenderableOrFactory
  description?: RenderableOrFactory
  custom?: CustomContent
  promise?: PromiseInput<unknown>
}

type ToastSubscriber = (toast: ToastT | ToastToDismiss) => void

These support direct ToastState and mountToaster() integrations. They share the global state unless advanced code injects another state object. Read the API reference before using them.

Browser registry type

interface NotifyApi {
  toast: typeof toast
  Toaster: (options?: ToasterOptions) => ToasterController
  createToaster: (options?: ToasterOptions) => ToasterController
  configureToaster: (options?: ToasterOptions) => ToasterController
  getToaster: () => ToasterController | null
  destroyToaster: () => void
}

The root browser export, the @samline/notify/browser default and named exports, and window.Notify expose this shape. resetToasts and the advanced exports are not properties of NotifyApi.

Public constants

import {
  GAP, // 14 pixels
  MOBILE_VIEWPORT_OFFSET, // '16px'
  SWIPE_THRESHOLD, // 45 pixels
  TIME_BEFORE_UNMOUNT, // 200 milliseconds
  TOAST_LIFETIME, // 4000 milliseconds
  TOAST_WIDTH, // 356 pixels
  VIEWPORT_OFFSET, // '24px'
  VISIBLE_TOASTS_AMOUNT, // 3
} from '@samline/notify'

TIME_BEFORE_UNMOUNT is the no-transition cleanup fallback. With CSS transitions active, removal waits for the longest transition and uses a computed timeout fallback instead of assuming 200 milliseconds.

Type usage notes

  • ToastId is number | string. Numeric 1 and string ‘1’ are different identities even when their data-id text is identical.
  • RenderableOrFactory callbacks are evaluated when a state record is created or updated; calling the factory again with the same id evaluates the new callback again. They are not a reactive subscription.
  • CustomContent mounts an owned element directly or invokes the callback with a div[data-custom] and a { id, dismiss } context. The callback can run again after toaster updates; return a cleanup function to release its listeners. Use textContent for untrusted text.
  • ToastAction.closeOnClick defaults to true for action and cancel. Set false only when the action should leave the toast open.
  • ToasterController.element is the mounted ordered list; options is the current merged configuration. update returns the same controller. destroy clears listeners/timers and removes that container; use destroyToaster to publish global dismissals too.
  • Position determines swipe availability. Direction ‘auto’ reads document direction. Theme ‘system’ resolves and follows matchMedia changes in JavaScript, rather than relying on a stylesheet-only media query.
  • Offset numbers receive px; strings are forwarded. Omitted object sides use 24px desktop or 16px mobile defaults.
  • SwipeDirection describes the directions derived from a position: both edges of a corner, or the vertical edge of a centered position.
  • PromiseInput thunks with data run immediately; without data, each unwrap invocation runs the thunk. PromiseValue and PromiseExtendedResult let a settled message override toast options; finally waits for the rendering callback pipeline.
  • NotifyApi describes the registry exposed as window.Notify.