Installation

npm install svileo
# or
pnpm add svileo
# or
yarn add svileo

Setup

Add the Toaster component once, near the root of your app (e.g. in a layout file):

<script>
  import { Toaster } from 'svileo';
  import 'svileo/styles.css';

  let { children } = $props();
</script>

<Toaster />
{@render children()}

Usage

Import svileo and call any of its methods from anywhere in your app:

<script>
  import { svileo } from 'svileo';
</script>

<button onclick={() => svileo.success({ title: 'Saved!' })}>
  Save
</button>

API

svileo.show(options)

Show a toast with an explicit type.

svileo.show({ title: 'Hello', type: 'info' });

svileo.success(options)

svileo.error(options)

svileo.warning(options)

svileo.info(options)

svileo.action(options)

Convenience methods for each toast state.

svileo.success({ title: 'File saved' });
svileo.error({ title: 'Something went wrong', description: 'Please try again.' });
svileo.warning({ title: 'Low disk space' });
svileo.info({ title: 'Update available' });
svileo.action({ title: 'Undo delete', button: { title: 'Undo', onClick: () => restore() } });

svileo.promise(promise, options)

Shows a loading toast while the promise is pending, then transitions to success, error, or action.

svileo.promise(saveFile(), {
  loading: { title: 'Saving…' },
  success: { title: 'File saved!' },
  error:   (err) => ({ title: 'Failed', description: err.message }),
});

The action key can be used instead of success to show an action toast on resolve:

svileo.promise(deleteItem(id), {
  loading: { title: 'Deleting…' },
  success: { title: 'Deleted' },
  action:  (data) => ({
    title: 'Item deleted',
    button: { title: 'Undo', onClick: () => restore(data) },
  }),
  error: { title: 'Error deleting item' },
});

svileo.dismiss(id)

Dismiss a specific toast by its ID.

const id = svileo.info({ title: 'Processing…', duration: null });
// later…
svileo.dismiss(id);

svileo.clear(position?)

Dismiss all toasts, or all toasts at a given position.

svileo.clear();
svileo.clear('top-right');

SvileoOptions

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | — | Toast heading | | description | string \| Snippet | — | Body text or a Svelte Snippet | | type | SvileoState | 'success' | Toast variant | | position | SvileoPosition | Toaster default | Where the toast appears | | duration | number \| null | 6000 | Auto-dismiss after ms. null = persist | | icon | Snippet \| null | — | Custom icon Snippet. null disables the icon | | styles | SvileoStyles | — | CSS class overrides | | fill | string | — | Custom background colour | | roundness | number | 16 | Border radius in px | | autopilot | boolean \| { expand?: number; collapse?: number } | true | Automatically expand/collapse the toast | | button | SvileoButton | — | Inline action button |

SvileoState

'success' | 'loading' | 'error' | 'warning' | 'info' | 'action'

SvileoPosition

'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'

SvileoStyles

interface SvileoStyles {
  title?:       string; // CSS class applied to the title
  description?: string; // CSS class applied to the description
  badge?:       string; // CSS class applied to the icon badge
  button?:      string; // CSS class applied to the action button
}

SvileoButton

interface SvileoButton {
  title:   string;
  onClick: () => void;
}

<Toaster> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | SvileoPosition | 'top-right' | Default position for all toasts | | offset | number \| string \| OffsetConfig | — | Distance from the screen edge | | options | Partial<SvileoOptions> | — | Global defaults applied to every toast | | theme | 'light' \| 'dark' \| 'system' | 'system' | Colour scheme |

offset can be a single value applied to all sides, or an object with individual top, right, bottom, left keys.

<Toaster position="bottom-center" offset={24} theme="dark" />

Styling

Import the base stylesheet once at your app root:

import 'svileo/styles.css';

Per-toast class overrides can be passed via the styles prop on any toast option.

Credits

Svileo is a Svelte 5 port of Sileo, the original physics-based React toast library created by Aaryan (@hiaaryan). The design, animation model, and API shape all originate from his work.

License

MIT © Elyas Asmad