✨ Features

• 🎯 Physics-Based Animations — Smooth spring animations powered by Svelte's motion stores
• 🫧 SVG Gooey Morphing — Organic blob-like shape transitions using SVG filters
• 📍 6 Positions — Place toasts anywhere: top/bottom + left/center/right
• 🎨 5 States — Success, error, warning, info, and action states (plus loading)
• 🔄 Auto Expand/Collapse — Toasts expand on hover to reveal descriptions
• 👆 Swipe to Dismiss — Touch-friendly gesture support
• 📚 Stacking Animations — New toasts push existing ones naturally
• ♿ Accessible — ARIA live regions for screen readers
• 🎛️ Fully Customizable — CSS variables for complete control
• 📦 Tiny Bundle — No external dependencies beyond Svelte
• 💪 TypeScript — Full type safety out of the box

📦 Installation

# npm
npm install sileo-sveltekit

# pnpm
pnpm add sileo-sveltekit

# yarn
yarn add sileo-sveltekit

# bun
bun add sileo-sveltekit

Requirements

• Svelte 5.0+
• SvelteKit 2.0+

🚀 Quick Start

1. Add the Toaster to your layout

Add the Toaster component to your root layout. This renders the toast container and sets up the global toast API.

<!-- src/routes/+layout.svelte -->
<script>
  import { Toaster } from 'sileo-sveltekit';
</script>

<Toaster />

<slot />

2. Show toasts from anywhere

Use the global window.toast API to show notifications from any component:

<script>
  function handleClick() {
    window.toast.success('Saved!', 'Your changes have been saved successfully.');
  }
</script>

<button on:click={handleClick}>
  Save Changes
</button>

That's it! You're ready to show beautiful toast notifications.

📖 API Reference

Toaster Component

The main component that renders the toast container.

<Toaster position="bottom-right" />

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | SileoPosition | 'bottom-right' | Default position for all toasts |

Position Options

| Value | Description | |-------|-------------| | 'top-left' | Top left corner | | 'top-center' | Top center | | 'top-right' | Top right corner | | 'bottom-left' | Bottom left corner | | 'bottom-center' | Bottom center | | 'bottom-right' | Bottom right corner |

Toast API

The toast API is available globally via window.toast.

Quick Methods

// Success toast
window.toast.success(title: string, description?: string, duration?: number): string

// Error toast
window.toast.error(title: string, description?: string, duration?: number): string

// Warning toast
window.toast.warning(title: string, description?: string, duration?: number): string

// Info toast
window.toast.info(title: string, description?: string, duration?: number): string

// Action toast
window.toast.action(title: string, description?: string, duration?: number): string

Returns: Toast ID (string) — useful for programmatic dismissal

Show with Options

For full control, use toast.show() with an options object:

window.toast.show({
  title: 'Custom Toast',
  description: 'With all the options',
  position: 'top-center',
  duration: 5000,
  fill: '#1a1a1a',
  roundness: 20,
  autopilot: true
}): string

Options Object

| Property | Type | Default | Description | |----------|------|---------|-------------| | title | string | — | Toast title (required) | | description | string | — | Optional description text | | position | SileoPosition | Toaster default | Override position for this toast | | duration | number \| null | 6000 | Auto-dismiss delay in ms. Use null for persistent | | fill | string | '#fff' | Background color (CSS color value) | | roundness | number | 16 | Border radius in pixels | | autopilot | boolean \| object | true | Auto expand/collapse behavior |

Autopilot Options

Control automatic expand/collapse timing:

window.toast.show({
  title: 'Custom timing',
  description: 'This toast has custom autopilot',
  autopilot: {
    expand: 500,    // Expand after 500ms
    collapse: 3000  // Collapse after 3000ms
  }
})

Set autopilot: false to disable auto expand/collapse entirely.

Dismiss Methods

// Dismiss a specific toast by ID
window.toast.dismiss(id: string): void

// Clear all toasts
window.toast.clear(): void

// Clear toasts at a specific position
window.toast.clear('top-right'): void

🎨 Customization

CSS Variables

Customize the appearance by overriding CSS variables in your global styles:

:root {
  /* Dimensions */
  --sileo-height: 40px;
  --sileo-width: 350px;

  /* Animation */
  --sileo-duration: 600ms;

  /* Default colors */
  --sileo-fill: #ffffff;
  --sileo-text: currentColor;

  /* State colors (using oklch for vibrant colors) */
  --sileo-state-success: oklch(0.723 0.219 142.136);
  --sileo-state-error: oklch(0.637 0.237 25.331);
  --sileo-state-warning: oklch(0.795 0.184 86.047);
  --sileo-state-info: oklch(0.685 0.169 237.323);
  --sileo-state-action: oklch(0.623 0.214 259.815);
  --sileo-state-loading: oklch(0.556 0 0);
}

Dark Mode

Sileo automatically adapts to your color scheme. Override the fill color for dark mode:

:root.dark {
  --sileo-fill: #1a1a1a;
  --sileo-text: #ffffff;
}

Or set the fill per-toast:

window.toast.success('Dark toast', 'With custom background', {
  fill: '#1a1a1a'
})

Custom State Colors

Change the colors for each toast state:

:root {
  /* Use your brand colors */
  --sileo-state-success: #10b981;
  --sileo-state-error: #ef4444;
  --sileo-state-warning: #f59e0b;
  --sileo-state-info: #3b82f6;
  --sileo-state-action: #8b5cf6;
}

💡 Examples

Basic Usage

<script>
  function showToasts() {
    window.toast.success('Success!', 'Operation completed');
    window.toast.error('Error!', 'Something went wrong');
    window.toast.warning('Warning!', 'Please check this');
    window.toast.info('Info', 'Here is some information');
  }
</script>

<button on:click={showToasts}>Show All Types</button>

Persistent Toast

<script>
  let toastId;

  function showPersistent() {
    toastId = window.toast.show({
      title: 'Uploading...',
      description: 'Please wait while we upload your file',
      duration: null // Never auto-dismiss
    });
  }

  function dismiss() {
    window.toast.dismiss(toastId);
  }
</script>

<button on:click={showPersistent}>Start Upload</button>
<button on:click={dismiss}>Cancel</button>

Promise Pattern

<script>
  async function saveData() {
    const id = window.toast.show({
      title: 'Saving...',
      description: 'Please wait',
      duration: null
    });

    try {
      await fetch('/api/save', { method: 'POST' });
      window.toast.dismiss(id);
      window.toast.success('Saved!', 'Your data has been saved');
    } catch (error) {
      window.toast.dismiss(id);
      window.toast.error('Failed', 'Could not save your data');
    }
  }
</script>

Different Positions

<script>
  function topLeft() {
    window.toast.show({
      title: 'Top Left',
      position: 'top-left'
    });
  }

  function bottomCenter() {
    window.toast.show({
      title: 'Bottom Center',
      position: 'bottom-center'
    });
  }
</script>

<button on:click={topLeft}>Top Left</button>
<button on:click={bottomCenter}>Bottom Center</button>

Custom Styling

<script>
  function customToast() {
    window.toast.show({
      title: 'Custom Toast',
      description: 'With brand colors and rounded corners',
      fill: '#ff4b26',
      roundness: 24
    });
  }
</script>

📘 TypeScript

Full TypeScript support with exported types:

import type {
  SileoState,      // 'success' | 'error' | 'warning' | 'info' | 'action' | 'loading'
  SileoPosition,   // 'top-left' | 'top-center' | ... | 'bottom-right'
  SileoOptions,    // Options for toast.show()
  SileoToastAPI    // Type for window.toast
} from 'sileo-sveltekit';

Type-Safe Global Toast

Add type safety to window.toast:

// src/app.d.ts
import type { SileoToastAPI } from 'sileo-sveltekit';

declare global {
  interface Window {
    toast: SileoToastAPI;
  }
}

export {};

🔧 Advanced Configuration

Multiple Toaster Instances

While one Toaster handles all positions, you can customize behavior:

<script>
  import { Toaster } from 'sileo-sveltekit';
</script>

<!-- Primary toaster for most notifications -->
<Toaster position="bottom-right" />

Disable Autopilot

Prevent toasts from auto-expanding:

window.toast.show({
  title: 'Manual Only',
  description: 'This only expands on hover',
  autopilot: false
});

Reduced Motion

Sileo respects prefers-reduced-motion. When enabled, animations are minimized for accessibility.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🙏 Credits

• Original sileo by @hiaaryan
• SvelteKit port by Cairo Studio