Components

Solid Notifications provides several key components to manage and display notifications.

ToastProvider

<ToastProvider />

The ToastProvider is a context provider component that manages the state and functionality of toasters within your application. It serves as the central hub for registering, retrieving, and unregistering toasters, as well as providing configuration options for toast notifications.

Wrap your application (or a specific part of it) with the ToastProvider to enable toast functionality. This component should be placed at a high level in your component tree to ensure that all child components have access to the toast context.

import { ToastProvider } from "solid-notifications";

export default function App(props) {
  return <ToastProvider>{props.children}</ToastProvider>;
}

Props

The ToastProvider accepts toaster config props, toast config props and children.

• Global Props and Propagation

  Props set on the ToastProvider are global and apply to all toasters and toasts within its context. These global settings propagate down to individual toasters and toasts, ensuring consistent behavior and styling across your application.

• Reactive Props

  The ToastProvider also accepts reactive props. This means you can pass SolidJS signals or derived values as props, and they will dynamically update the global configuration. For example, if you want to change the toast position or theme dynamically based on user preferences, you can pass a signal as the position prop.

Toaster

<Toaster />

The Toaster component is responsible for rendering and managing a collection of toasts. It acts as a container for toasts, handling their lifecycle, positioning, and behavior based on global and local configuration settings. Each Toaster instance is registered with the ToastProvider and can be uniquely identified by its toasterId.

import { Toaster } from "solid-notifications";

export default function App(props) {
  return (
    <>
      <Toaster toasterId="primary" />
      <Toaster toasterId="secondary" />
      {props.children}
    </>
  );
}

• Multiple Toaster Support: Allows you to create multiple toasters, each with its own configuration settings.

• Toast Management: Manages a queue of toasts and renders them based on configuration settings like limit and reverseToastOrder.

• Dynamic Positioning: Automatically calculates and updates toast positions based on their height, gutter spacing, and offset.

• Window Visibility Handling: Pauses toast progress when the window is inactive (blurred) and resumes when the window is active (focused), depending on configuration.

• Reactive Configuration: Supports reactive updates to its configuration, which propagate to all toasts within the toaster.

Props

The Toaster component accepts toaster config, toast config props and toasterId.

Toast

class Toast

The Toast class represents an individual notification message. They are invoked by the provided functions and rendered within a Toaster instance. Each toast can be customized with various options like content, duration, and appearance.

import { useToast } from "solid-notifications";

export default function App() {
  const { notify } = useToast();

  return (
    <button
      onClick={() =>
        notify("Hello, World!", {
          duration: 5000,
          type: "success",
          exitCallback: (reason) =>
            console.log(`Toast exited because: ${reason}`),
        })
      }
    >
      Show Toast
    </button>
  );
}

• Customizable Content: Supports custom content, including text, HTML, or JSX elements.
• Appearance Options: Supports various appearance options like type, icon, and theme.
• Lifecycle Callbacks: Provides callbacks for toast lifecycle events like onEnter, onExit, and exitCallback.
• Reactive Configuration: Supports reactive updates to its configuration.
• Global and Local Overrides: Overrides global settings provided by the ToastProvider or Toaster.

Props

Accepts toast config props as well as id and toasterId (other config). Also accepts content props when updating a toast. Any props specified when creating or updating a toast will take precedence over global settings.

Properties available on the Toast instance

These properties can be accesed when using a custom toast.

class Toast {
  store;
  toastConfig: Config;
  ref: HTMLElement | null = null;
  state: "entering" | "idle" | "exiting" = "entering";
  renderedAt: number | undefined;
  progressManager: ReturnType<typeof createProgressManager>;
  isPaused = true;
  isPausedByUser = false;
  offset = 0;

...
}

Each toast instance has several properties that define its behavior and appearance.

• store: A reference to the Toaster store that manages the toast.
• toastConfig: The configuration properties of the toast.
• ref: A reference to the toast's DOM element.
• state: Represents the lifecycle of the toast. It can be "entering" when the toast is animating into view, "idle" when fully visible, and "exiting" when it is dismissed.
• renderedAt: A timestamp indicating when the toast was rendered. Useful as a flag to determine if the toast is visible.
• progressManager: An object responsible for managing the toast's progress bar and duration.
• isPaused: A flag that indicates whether the toast's timer is currently paused.
• isPausedByUser: Similar to isPaused, but specifically tracks whether the user manually paused the toast, for example by pressing a button.
• offset: Represents the vertical position of the toast relative to other active toasts.