Toast — React

Installation

npm install @fluix-ui/react @fluix-ui/css

Basic Usage

import { Toaster, fluix } from "@fluix-ui/react";
import "@fluix-ui/css";

function App() {
  return (
    <>
      <Toaster position="top-right" />
      <button onClick={() => fluix.success({ title: "Saved!" })}>
        Save
      </button>
    </>
  );
}

Add <Toaster /> once in your app (typically in your root layout). Then call fluix.success(), fluix.error(), etc. from anywhere.

Toaster Component

<Toaster
  position="top-right"
  config={{
    layout: "stack",
    offset: 24,
    defaults: {
      theme: "dark",
      duration: 6000,
      roundness: 16,
    },
  }}
/>

Props

Prop	Type	Default	Description
`position`	`FluixPosition`	`"top-right"`	Default viewport position
`config`	`FluixToasterConfig`	—	Full configuration object

The config prop accepts position, layout, offset, and defaults. See API Reference.

Toast Options

Call fluix.success() from any React component, hook, or utility function. Since fluix is a singleton, it works without context or providers — perfect for onClick handlers, useEffect callbacks, or API response handlers.

// Inside a React component
function SettingsPage() {
  const handleSave = async () => {
    await saveSettings();
    fluix.success({
      title: "Settings saved",
      description: "Your preferences have been updated.",
      duration: 5000,
      theme: "dark",
      roundness: 20,
      icon: "✨",
      styles: {
        title: "custom-title-class",
        description: "custom-desc-class",
      },
    });
  };

  return <button onClick={handleSave}>Save</button>;
}

The theme option accepts any string — "light", "dark", or a custom name you define in CSS. See Theming for details.

Promise Support

Wrap any Promise to show a loading toast that transitions to success or error automatically. This is useful for data fetching in event handlers or useEffect:

function UserList() {
  const loadUsers = () => {
    fluix.promise(
      fetch("/api/users").then((r) => r.json()),
      {
        loading: { title: "Loading users..." },
        success: (users) => ({
          title: "Users loaded",
          description: `Found ${users.length} users`,
        }),
        error: (err) => ({
          title: "Failed to load",
          description: err.message,
        }),
      }
    );
  };

  return <button onClick={loadUsers}>Refresh</button>;
}

Action Button

Show a toast with an undo action — useful after destructive operations like deleting items. The callback runs when the user clicks the button:

function ItemRow({ item, onDelete, onRestore }) {
  const handleDelete = () => {
    onDelete(item.id);
    fluix.action({
      title: "Item deleted",
      description: `"${item.name}" has been removed.`,
      button: {
        title: "Undo",
        onClick: () => {
          onRestore(item.id);
          fluix.success({ title: "Restored!" });
        },
      },
    });
  };

  return <button onClick={handleDelete}>Delete</button>;
}

Custom Description (JSX)

React adapter supports JSX in the description field:

fluix.success({
  title: "Booking Confirmed",
  description: (
    <div className="booking-card">
      <strong>Flight UA-920</strong>
      <span>DEL → SFO</span>
    </div>
  ),
});

Layout Modes

// Stack: vertical list of individual toasts
<Toaster config={{ layout: "stack" }} />

// Notch: compact island (toasts share one container)
<Toaster config={{ layout: "notch" }} />

How It Works in React

The React adapter uses useSyncExternalStore to subscribe to the Fluix core store. This means toast state updates follow React’s concurrent rendering model and batch correctly with other state changes.

The <Toaster /> component renders a position: fixed viewport with ARIA live regions. Each toast is a <button> element for keyboard accessibility. The SVG gooey morphing effect runs entirely through SVG filters — no React re-renders are needed for animation frames.

The fluix object is a singleton — you can import it in any file and fire toasts without prop drilling or context providers.