Sileo

Install the sileo package using npm to use the physics-based toast component in your React project.

npm i sileo

To use Sileo, you must include the Toaster component at the root of your application. The Toaster accepts a position prop to determine where toasts will appear (e.g., top-right). You can then use the sileo function to trigger toasts.

import { sileo, Toaster } from "sileo";

export default function App() {
  return (
    <>
      <Toaster position="top-right" />
      <YourApp />
    </>
  );
}

Toasts can be configured with an autopilot setting within their options to control how they behave when they appear or disappear. This is useful for managing how long a toast stays expanded or how quickly it collapses.

autopilot can be a boolean or an object:

• autopilot: true: Uses default delays.
• autopilot: { expand: number, collapse: number }: Sets custom delay durations in milliseconds.

Note: If duration is set to null, the toast will not auto-dismiss.

Sileo features two modes of interaction:

1. Expansion: If a description or button is provided, the toast can expand from a small 'pill' into a larger notification. Expansion can be triggered by hovering (onMouseEnter) or automatically via autoExpandDelayMs. When expanded, the component shows the description and any button provided.
2. Dismissal: Users can dismiss the toast by swiping it vertically. The onDismiss callback is triggered if the swipe distance exceeds the internal threshold (SWIPE_DISMISS).

Note on Refreshing: To update the content of an already visible toast (e.g., changing a state from loading to success), use the refreshKey prop. This ensures smooth transitions between different view states.

Sileo provides a set of pre-defined SVG icon components that can be used in your UI, such as within toast notifications. These components accept standard SVGProps<SVGSVGElement> (like className, style, width, height, etc.), allowing you to customize their appearance.

Available icons include:

• ArrowRight
• LifeBuoy
• LoaderCircle
• X
• CircleAlert
• Check

The sileo object provides a programmatic API to trigger different types of toast notifications. Most methods return a unique id which can be used to manually dismiss or update the toast later.

Available Methods

• show(opts): Triggers a generic toast.
• success(opts): Triggers a success state toast.
• error(opts): Triggers an error state toast.
• warning(opts): Triggers a warning state toast.
• info(opts): Triggers an info state toast.
• action(opts): Triggers an action state toast.
• dismiss(id): Manually removes a specific toast by its ID.
• clear(position?): Removes all toasts, or all toasts at a specific SileoPosition if provided.

The promise method allows you to link the lifecycle of a toast to a JavaScript Promise. It automatically manages a 'loading' state and transitions to 'success', 'error', or 'action' based on the promise outcome.

SileoPromiseOptions<T>

• loading: SileoOptions used while the promise is pending.
• success: SileoOptions or a callback (data: T) => SileoOptions used when the promise resolves.
• error: SileoOptions or a callback (err: unknown) => SileoOptions used when the promise rejects.
• action: (Optional) SileoOptions or a callback (data: T) => SileoOptions used if an action state is desired after resolution.
• position: The position for the toast lifecycle.

The Toaster component is the UI entry point that renders toast notifications. It should be placed at the top level of your application. It accepts configuration for positioning, offsets, global options, and themes.

Props

• position: The default position for toasts (e.g., top-right).
• offset: A number, string, or SileoOffsetConfig object to define the distance from the viewport edges.
• options: Global SileoOptions applied to all toasts.
• theme: Sets the color scheme to 'light', 'dark', or 'system' (which follows the user's OS preference).

The SileoPosition type defines where the notification is anchored on the screen. The available positions are:

• top-left
• top-center
• top-right
• bottom-left
• bottom-center
• bottom-right

export const SILEO_POSITIONS = [
	"top-left",
	"top-center",
	"top-right",
	"bottom-left",
	"bottom-center",
	"bottom-right",
] as const;

export type SileoPosition = (typeof SILEO_POSITIONS)[number];