Toast

Cherry's toast system shows short, animated notifications in a fixed stack. It consists of three parts: a provider that holds the state, a component that renders the stack, and a hook to fire notifications from anywhere in the tree.

For design guidelines and all interactive states, see the Overlays design page.

Wrap your app with the provider and render the stack once. The example assumes the Cherry theme provider from Installation is already set up; rendering a toast without a theme throws:

"use client";
import React from "react";
import {
  ToastNotifications,
  ToastNotificationsProvider,
} from "cherry-styled-components";

export default function App({ children }) {
  return (
    <ToastNotificationsProvider>
      <ToastNotifications />
      {children}
    </ToastNotificationsProvider>
  );
}

Fire notifications with the useToastNotifications hook:

"use client";
import React from "react";
import { Button, useToastNotifications } from "cherry-styled-components";

export default function SaveButton() {
  const { addNotification } = useToastNotifications();

  return (
    <Button
      onClick={() =>
        addNotification("Changes saved successfully.", {
          color: "success",
          autoHide: 4000,
        })
      }
    >
      Save
    </Button>
  );
}

A toast without autoHide stays until the user dismisses it with the built-in close button. Either way, once a toast has animated out it is removed from the stack entirely. The stack is an aria-live="polite" region, so screen readers announce new toasts as they appear.

Properties

useToastNotifications returns { notifications, addNotification, removeNotification }. The notifications array holds the toasts currently in the stack; each entry carries a unique numeric id plus its text, resolved color, and autoHide value.

addNotification

removeNotification

Removes a toast from state immediately, skipping the exit animation. You rarely need this yourself: the close button and autoHide already remove toasts after their exit animation.

ToastNotifications

Exports

The library also exports the types ToastColor ("info" | "success" | "error" | "warning"), ToastAlign ("center" | "left" | "right"), and ToastConfig ({ color?, autoHide? }; addNotification defaults color to "info" and autoHide to 0, which keeps the toast until dismissed). For advanced use it exposes ToastNotificationsContext, the context behind the hook, and the styled primitives StyledNotifications and StyledNotificationItem.