Description:
Sileo is a React toast library that animates with spring physics and SVG morphing.
It enables you to create modern, smooth toast notifications as movable objects with realistic motion.
Each toast expands, collapses, and transitions using gooey filter effects.
Features
- 🎨 Variant System: Five preconfigured toast types (success, error, warning, info, action) with color-coded badges.
- ⚙️ Promise Integration: Call
sileo.promise()with any Promise to automatically show loading, success, and error states. - 📍 Six Position Options: Top-left, top-center, top-right, bottom-left, bottom-center, or bottom-right.
- 🎯 Action Buttons: Attach an onClick handler to any toast through the
buttonprop. - 🎨 Style Overrides: Pass custom classes to individual toast elements (title, description, badge, button) via the
stylesprop. - ⏱️ Duration Control: Set auto-dismiss timing per toast or disable dismissal entirely by passing
null. - 🖼️ Custom Icons: Replace default state icons with custom React nodes.
- 🌈 Fill Colors: Override badge background colors or switch to full dark mode with the
fillprop.
Use Cases
- Form Submissions: Show success or error feedback after users submit forms through the interface.
- File Operations: Display progress and completion status when users upload, download, or delete files.
- Background Tasks: Notify users about long-running operations that complete outside the current view.
- Validation Warnings: Alert users about input errors or missing required fields through non-blocking notifications.
How to Use It
Install the Package
Add Sileo to your project.
npm i sileoMount the Toaster Component
Import the Toaster component and place it in your app root. This component manages all toast instances.
import { Toaster } from "sileo";
export default function App() {
return (
<>
<Toaster position="top-right" />
<YourApp />
</>
);
}The position prop sets the default location for all toasts. You can override this per toast later.
Fire Basic Toasts
Import the sileo object and call methods based on the notification type.
import { sileo } from "sileo";
// Success notification
sileo.success({ title: "Changes saved" });
// Error notification
sileo.error({
title: "Something went wrong",
description: "Please try again later.",
});
// Warning notification
sileo.warning({ title: "Storage almost full" });
// Info notification
sileo.info({ title: "New update available" });Each method takes an options object. The title prop is required, while description is optional.
Add Action Buttons
Use sileo.action() to include an interactive button in the toast.
sileo.action({
title: "File uploaded",
description: "Share it with your team?",
button: {
title: "Share",
onClick: () => console.log("Shared!"),
},
});The button object requires a title string and an onClick handler.
Handle Promises
Pass a Promise to sileo.promise() to automatically cycle through loading, success, and error states.
sileo.promise(fetchData(), {
loading: { title: "Loading..." },
success: { title: "Done!" },
error: { title: "Failed" },
});The library updates the same toast instance as the Promise resolves or rejects. You can also pass functions to success and error to access the resolved data.
sileo.promise(createUser(data), {
loading: { title: "Creating account..." },
success: (user) => ({
title: `Welcome, ${user.name}!`,
}),
error: (err) => ({
title: "Signup failed",
description: err.message,
}),
});Override Position Per Toast
Set a custom position on individual toasts to override the default.
sileo.success({
title: "Saved",
position: "bottom-center",
});Available positions include top-left, top-center, top-right, bottom-left, bottom-center, and bottom-right.
Customize Styling
Pass class names through the styles prop to target specific toast elements.
sileo.success({
title: "Custom styled",
fill: "black",
styles: {
title: "text-white!",
description: "text-white/75!",
badge: "bg-white/20!",
button: "bg-white/10!",
},
});The fill prop changes the badge background color. Use "black" for full dark mode styling.
Control Auto-Dismiss
Set a custom duration in milliseconds or disable auto-dismiss entirely.
sileo.info({
title: "Important notice",
duration: 10000, // 10 seconds
});
sileo.warning({
title: "Action required",
duration: null, // Never auto-dismiss
});The default duration is 6000 milliseconds (6 seconds).
Configure Global Defaults
Pass default options to the Toaster component to apply settings across all toasts.
<Toaster
position="top-right"
offset={20}
options={{
fill: "#171717",
styles: { description: "text-white/75!" },
}}
/>The offset prop controls the distance from viewport edges. You can pass a number, string, or per-side configuration.
<Toaster offset={{ top: 20, right: 16 }} />API Reference
Toast Methods
- sileo.success(options): Renders a green success toast.
- sileo.error(options): Renders a red error toast.
- sileo.warning(options): Renders an amber warning toast.
- sileo.info(options): Renders a blue info toast.
- sileo.action(options): Renders a toast with an action button.
- sileo.show(options): Renders a generic toast without a state badge.
- sileo.promise(promise, options): Manages loading, success, and error states for a Promise.
ToastOptions
- title (string, required): Toast heading text.
- description (ReactNode | string, optional): Body content. Accepts JSX or plain text.
- position (ToastPosition, optional): Override the default position. Options are
top-left,top-center,top-right,bottom-left,bottom-center, andbottom-right. - duration (number | null, optional): Auto-dismiss timing in milliseconds. Default is 6000. Pass
nullto disable auto-dismiss. - icon (ReactNode | null, optional): Custom icon to replace the default state icon.
- fill (string, optional): Badge background color. Use
"black"for full dark mode. - styles (ToastStyles, optional): Class overrides for toast sub-elements.
- roundness (number, optional): Border radius in pixels. Default is 18.
- autopilot (boolean | object, optional): Controls auto expand/collapse timing. Default is
true. - button (ToastButton, optional): Configuration for action button.
ToastStyles Interface
- title (string, optional): Class name for the title element.
- description (string, optional): Class name for the description element.
- badge (string, optional): Class name for the badge element.
- button (string, optional): Class name for the button element.
ToastPromiseOptions Interface
- loading (object, required): Options for the loading state. Supports
titleandiconprops. - success (ToastOptions | function, required): Static options or callback that receives the resolved value.
- error (ToastOptions | function, required): Static options or callback that receives the rejected error.
Toaster Props
- position (ToastPosition, optional): Default position for all toasts. Default is
"top-right". - offset (number | string | object, optional): Distance from viewport edges. Default is 16. Accepts a number, string, or per-side configuration like
{ top: 20, right: 16 }. - options (Partial, optional): Default options merged into every toast.
Related Resources
- react-hot-toast: Renders lightweight toast components with customizable animations and transitions.
- sonner: Toast notifications with keyboard shortcuts and gesture controls built in.
- react-toastify: Notifications with progress bars, auto-close timers, and stacking options.
FAQs
Q: Can I change the position of a single toast?
A: Yes. You pass a position property to the options object when calling a method like sileo.success(). This overrides the global setting on the <Toaster />.
Q: How do I keep a toast on the screen indefinitely?
A: Set the duration property to null in the options object. The toast remains visible until the user dismisses it manually.
Q: Does Sileo support dark mode?
A: The library supports custom colors. You can set the fill property to “black” or use the styles object to apply dark mode CSS classes to the toast elements.
Q: Can I use custom icons instead of the default ones?
A: Yes. The icon property accepts any React Node. You can pass an SVG or a component to replace the standard status badge.