# Sileo Svelte complete documentation

<!-- Source: /docs.md -->

---
title: Sileo Svelte
description: Physics-based toast notifications for Svelte 5, with typed helpers, promise states, actions, and rich snippets.
label: Overview
---

Sileo Svelte displays compact notifications. When content needs more room, a toast expands in place. Loading, success, and error messages can update the same toast instead of replacing it.

This package is an unofficial Svelte port of [the original Sileo library](https://github.com/hiaaryan/sileo).

## Start here

Install the package and its stylesheet.

```bash
bun add sileo-svelte
```

Mount one toaster near the root of your app.

```svelte
<script lang="ts">
    import { Toaster } from 'sileo-svelte';
    import 'sileo-svelte/styles.css';
</script>

<Toaster position="top-right" />
```

Call `sileo` from any client-side component.

```svelte
<script lang="ts">
    import { sileo } from 'sileo-svelte';

    function save() {
        sileo.success({
            title: 'Release saved',
            description: 'Draft v2.4 is ready for review.'
        });
    }
</script>

<button onclick={save}>Save release</button>
```

## What ships

- Six semantic states plus a neutral `show` helper.
- Updates that keep the same toast id.
- Promise flows with typed success data.
- Action buttons and persistent notifications.
- Svelte snippets for descriptions and icons.
- Per-toast classes, colors, and timing.

## Requirements

Sileo Svelte requires Svelte 5.56 or newer. Motion is included as a runtime dependency; the package has no utility CSS dependency. Import its stylesheet once, then use normal Svelte components and TypeScript.

## Try the real component

The [playground](/playground) runs every documented scenario against the package itself. Change the viewport position, run a flow, and copy the exact source beside it.

## Next step

Read [Installation](/docs/installation) for the full root layout setup and default options. Check the [Changelog](/docs/changelog) before upgrading between beta versions.

---

<!-- Source: /docs/installation.md -->

---
title: Installation
description: Add the package, import its styles, and mount one toaster for the application.
label: Installation
---

## Install the package

Use the package manager already used by your project. Sileo Svelte requires Svelte 5.56 or newer. The Motion runtime is installed with the package.

```bash
bun add sileo-svelte
```

```bash
npm install sileo-svelte
```

## Mount the toaster

Import the stylesheet once. In SvelteKit, the root layout is a good place for both imports.

```svelte
<script lang="ts">
    import { Toaster } from 'sileo-svelte';
    import 'sileo-svelte/styles.css';

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

{@render children()}
<Toaster position="top-right" />
```

`Toaster` also renders an optional `children` snippet. You can wrap the app instead if that fits your layout.

```svelte
<Toaster position="bottom-center">
    {@render children()}
</Toaster>
```

Mount one toaster. Multiple instances share the same store and make placement harder to reason about.

## Set application defaults

The `options` prop applies defaults to every toast. Individual calls can override them.

```svelte
<Toaster
    position="top-right"
    offset={{ top: 20, right: 20 }}
    options={{
        duration: 5000,
        roundness: 10,
        autopilot: true
    }}
/>
```

`offset` accepts one number, one CSS length, or an object with `top`, `right`, `bottom`, and `left` values.

## Server rendering

Mount the component in a normal Svelte layout. Call `sileo` in browser interactions such as button handlers, form results, or client-side tasks. Do not create notifications during server rendering.

## Confirm the setup

Add a temporary button and click it in the browser.

```svelte
<button onclick={() => sileo.info({ title: 'Toaster connected' })}> Test notification </button>
```

If nothing appears, check that the stylesheet import reaches the browser and that the toaster is mounted once.

---

<!-- Source: /docs/changelog.md -->

---
title: Changelog
description: Release history, compatibility notes, breaking changes, fixes, and upgrade guidance.
label: Changelog
---

This project is still in beta. Each release is marked as breaking or non-breaking so upgrades do not depend on version numbers alone.

## Unreleased

**Release impact: Breaking**

### Breaking changes

- The minimum supported Svelte version is now 5.56. This lets the package use modern element attachments without compatibility branches.

### Changed

- Toast motion now runs through the framework-independent `motion` package. CSS is responsible only for layout and appearance.
- Interrupted shape animations now retarget from their rendered geometry, and all active controls are released when a toast unmounts.
- Header states crossfade with a short blur and positional overlap instead of flashing between text values.
- Swipe gestures use progressive resistance, velocity-aware dismissal, and a spring return.
- Geometry calculations now live in a small typed module instead of being mixed into rendering and gesture code.
- `--sileo-duration` controls visual timing and lifecycle completion instead of competing with fixed removal timers.
- The documentation has a dark-first homepage, searchable Markdown pages, syntax highlighting, copy controls, machine-readable routes, and an isolated playground.

### Fixed

- Reduced-motion preferences now skip transform-heavy entrances, shape motion, header blur, and loader rotation.
- Playground examples no longer leak notifications into the documentation route.
- Toast geometry stays aligned after runtime width and height changes.
- Promise completions cannot overwrite a newer toast that reused the same id.
- Old close and dismiss timers cannot remove a newer toast that reused the same id.
- A stable live region now announces the first toast as well as later updates.
- Keyboard, pointer, touch, live-region, and narrow-viewport behavior have been hardened.

### Upgrade

Update Svelte before installing this release:

```bash
bun add -D svelte@^5.56.0
bun add sileo-svelte
```

`SileoPromiseOptions` now permits an `action` result without a redundant `success` mapping. Existing calls remain valid.

## 0.1.1 — 2026-05-20

**Release impact: Non-breaking**

- Corrected default lifetimes for loading, action, and promise-driven toasts.
- Raised the viewport stacking level so notifications remain above application chrome.
- Rendered toast actions with semantic buttons.

## 0.0.5 — 2026-02-18

**Release impact: Breaking**

- Renamed public props and updated examples to match the new API.
- Added CSS custom properties and custom class support.
- Improved the demo's dark theme.

## 0.0.2 — 2026-02-18

**Release impact: Initial beta release**

- Published the first npm beta with state helpers, toast updates, styling hooks, and starter documentation.

---

<!-- Source: /docs/creating-toasts.md -->

---
title: Creating toasts
description: Choose a state, update an existing notification, and control its lifetime.
label: Creating toasts
---

## State helpers

Each state helper returns the toast id.

```ts
import { sileo } from 'sileo-svelte';

const id = sileo.success({
    title: 'Release saved',
    description: 'Draft v2.4 is ready for review.'
});
```

Available helpers are `show`, `success`, `error`, `warning`, `info`, `action`, and `loading`.

```ts
sileo.error('Could not save the release');
sileo.warning('The token expires tomorrow');
sileo.info('A new build is available');
```

A string becomes the title. Pass an object when you need a description, position, duration, action, or visual override.

## Update one toast

Keep the id returned by the first call, then update that toast in place.

```ts
const id = sileo.loading({
    title: 'Publishing release',
    duration: null
});

await publishRelease();

sileo.update(id, {
    state: 'success',
    title: 'Release published',
    description: 'Traffic is moving to v2.4.'
});
```

Use this for one task with several states. Creating a new toast for every state makes the interface jump and leaves stale messages behind.

## Dismiss, close, and clear

```ts
sileo.dismiss(id);
sileo.close(id);
sileo.clear();
sileo.clear('bottom-right');
```

`dismiss` and `close` both retire one toast. `clear` retires every toast, or only those at a supplied position.

## Control duration

Pass a duration in milliseconds. Use `null` for a notification that must remain until code closes it or the person acts.

```ts
sileo.action({
    title: 'Payment needs attention',
    duration: null,
    button: {
        title: 'Retry',
        onClick: (id) => retryPayment(id)
    }
});
```

Persistent toasts need a clear action or a reliable programmatic close path.

## Reuse defaults

Create a scoped API when several notifications share settings.

```ts
const billing = sileo.with({
    duration: 4000,
    position: 'bottom-right'
});

billing.info({
    title: 'Invoice ready',
    description: 'Invoice 4921 can be downloaded.'
});
```

---

<!-- Source: /docs/async-flows.md -->

---
title: Async flows
description: Track promises with one notification that moves through loading, success, and error states.
label: Async flows
---

## Track a promise

Pass an existing promise or a function that returns one.

```ts
const result = await sileo.promise(uploadBuild(), {
    loading: { title: 'Uploading build' },
    success: (build) => ({
        title: 'Build uploaded',
        description: `${build.files} artifacts are ready.`
    }),
    error: (error) => ({
        title: 'Upload failed',
        description: error instanceof Error ? error.message : 'Try again.'
    })
});
```

The returned promise preserves the original result type. You can keep using `result` after the notification finishes.

## Reuse a loading toast

Pass an id when code already created the loading state.

```ts
const id = sileo.loading({
    title: 'Uploading build',
    position: 'bottom-left'
});

await sileo.promise(() => uploadBuild(), {
    id,
    loading: { title: 'Uploading build' },
    success: { title: 'Build uploaded' },
    error: { title: 'Upload failed' }
});
```

This keeps the same toast and position throughout the task.

## Add a follow-up action

The optional `action` mapping replaces the success state. Use it when the completed task has one useful next step instead of a passive confirmation.

```ts
await sileo.promise(() => createReport(), {
    loading: { title: 'Building report' },
    success: { title: 'Report ready' },
    error: { title: 'Report failed' },
    action: (report) => ({
        title: 'Report ready',
        button: {
            title: 'Open report',
            onClick: () => openReport(report.id)
        }
    })
});
```

## Handle retries

Update the same id when an action starts another request.

```ts
function retryPayment(id: string) {
    sileo.update(id, {
        state: 'loading',
        title: 'Retrying payment'
    });

    retry().then(
        () => sileo.update(id, { state: 'success', title: 'Payment captured' }),
        () => sileo.update(id, { state: 'error', title: 'Payment declined again' })
    );
}
```

---

<!-- Source: /docs/customization.md -->

---
title: Customization
description: Change placement, timing, color, classes, and rich content without replacing the package CSS.
label: Customization
---

## Position

Set a default on `Toaster`, then override it on individual calls when needed.

```svelte
<Toaster position="top-right" />
```

```ts
sileo.info({
    title: 'Download started',
    position: 'bottom-center'
});
```

Supported positions are `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, and `bottom-right`.

## Color and shape

Use `fill` for the toast background and `roundness` for its corner model.

```ts
sileo.action({
    title: 'Custom surface',
    fill: '#1f1f1f',
    roundness: 8,
    button: {
        title: 'Close',
        onClick: (id) => sileo.close(id)
    }
});
```

Keep enough contrast between the fill, text, badge, and button colors. Test both collapsed and expanded states.

## Motion timing

Set `--sileo-duration` to change the toast's visual motion. The default is `600ms`.

```css
:root {
    --sileo-duration: 500ms;
}
```

Sileo reads this value when a toast mounts and uses it for its Motion spring and state transitions. People who prefer reduced motion get immediate layout and opacity changes with no transform-heavy entrance or loader motion.

## Typed style slots

The `styles` object changes supported visual values on one toast.

```ts
sileo.success({
    title: 'Theme updated',
    styles: {
        titleColor: '#ffffff',
        descriptionColor: '#d4d4d4',
        buttonColor: '#000000',
        buttonBackground: '#ffffff'
    }
});
```

Use `classes` when the application already has a class-based styling system.

```ts
sileo.info({
    title: 'New comment',
    classes: {
        title: 'notification-title',
        description: 'notification-description',
        button: 'notification-action'
    }
});
```

## Rich descriptions and icons

Sileo accepts Svelte snippets for `description` and `icon`.

```svelte
<script lang="ts">
    import { sileo } from 'sileo-svelte';

    function showRelease() {
        sileo.info({
            title: 'Release details',
            description: releaseDetails,
            icon: releaseIcon
        });
    }
</script>

{#snippet releaseDetails()}
    <div>
        <strong>Release v2.4</strong>
        <span>Six regions are healthy.</span>
    </div>
{/snippet}

{#snippet releaseIcon()}
    <span aria-hidden="true">R</span>
{/snippet}

<button onclick={showRelease}>Show release</button>
```

Keep interactive controls in the toast button. Description snippets should explain the state, not contain another focus path.

---

<!-- Source: /docs/api.md -->

---
title: API reference
description: Methods exposed by sileo and the option types accepted by every toast.
label: API reference
---

## State methods

```ts
sileo.show(input, description?)
sileo.success(input, description?)
sileo.error(input, description?)
sileo.warning(input, description?)
sileo.info(input, description?)
sileo.action(input, description?)
sileo.loading(input, description?)
```

Each method accepts a title string or a `SileoOptions` object and returns the new toast id.

## Lifecycle methods

```ts
sileo.update(id, options)
sileo.dismiss(id)
sileo.close(id)
sileo.clear(position?)
```

`update` accepts every `SileoOptions` field plus an optional `state`. `clear` can target one of the six positions.

## Promise

```ts
sileo.promise<T>(
    promise: Promise<T> | (() => Promise<T>),
    options: SileoPromiseOptions<T>
): Promise<T>
```

```ts
type PromiseResult<T> = SileoOptions | ((data: T) => SileoOptions);

type SileoPromiseOptions<T> = {
    id?: string;
    loading: Pick<SileoOptions, 'title' | 'icon'>;
    error: SileoOptions | ((error: unknown) => SileoOptions);
    position?: SileoPosition;
} & ({ success: PromiseResult<T>; action?: undefined } | { action: PromiseResult<T>; success?: PromiseResult<T> });
```

Provide either `success` or `action`. If both are present, `action` becomes the final state.

## Scoped defaults

```ts
const scoped = sileo.with(defaults);
```

The returned object has the same state, promise, update, dismiss, close, and clear methods. Call-level options override scoped defaults.

## SileoOptions

| Field         | Type                | Purpose                                          |
| ------------- | ------------------- | ------------------------------------------------ |
| `title`       | `string`            | Primary notification text.                       |
| `description` | `string \| Snippet` | Supporting text or structured Svelte content.    |
| `position`    | `SileoPosition`     | Viewport placement for this toast.               |
| `duration`    | `number \| null`    | Lifetime in milliseconds. `null` keeps it open.  |
| `icon`        | `Snippet \| null`   | Custom icon content or no icon.                  |
| `button`      | `SileoButton`       | One labeled action with the toast id callback.   |
| `fill`        | `string`            | Toast background color.                          |
| `roundness`   | `number`            | Corner roundness used by the toast shape.        |
| `autopilot`   | `boolean \| object` | Automatic expand and collapse timing.            |
| `classes`     | `SileoClasses`      | Class names for supported internal parts.        |
| `styles`      | `SileoStyles`       | Typed color values for supported internal parts. |

## Exported types

```ts
import type {
    SileoApi,
    SileoButton,
    SileoClasses,
    SileoInput,
    SileoOptions,
    SileoPosition,
    SileoPromiseOptions,
    SileoScopedApi,
    SileoState,
    SileoStyles
} from 'sileo-svelte';
```

---

<!-- Source: /docs/toaster.md -->

---
title: Toaster reference
description: Configure the mounted toaster, viewport offsets, and application-wide defaults.
label: Toaster
---

## Props

```ts
interface ToasterProps {
    children?: Snippet;
    position?: SileoPosition;
    offset?:
        | number
        | string
        | {
              top?: number | string;
              right?: number | string;
              bottom?: number | string;
              left?: number | string;
          };
    options?: Partial<SileoOptions>;
}
```

## position

The default is `top-right`. A position passed to an individual toast overrides it.

```svelte
<Toaster position="bottom-center" />
```

## offset

A number becomes pixels. A string can use any CSS length. One value applies to all viewport edges.

```svelte
<Toaster offset={24} />
<Toaster offset="calc(env(safe-area-inset-top) + 16px)" />
```

Pass an object when each edge needs a different value.

```svelte
<Toaster
    offset={{
        top: 'calc(env(safe-area-inset-top) + 16px)',
        right: 16,
        bottom: 24,
        left: 16
    }}
/>
```

Only the edges used by a toast position affect that viewport.

## options

Use `options` for application defaults.

```svelte
<Toaster
    options={{
        duration: 6000,
        fill: '#181818',
        roundness: 10,
        autopilot: { expand: 120, collapse: 2800 }
    }}
/>
```

Precedence runs from application defaults to scoped defaults to options passed to the toast call.

## children

`children` is optional. When supplied, the toaster renders it before the notification viewports.

```svelte
<Toaster>
    {@render children()}
</Toaster>
```

This form is useful when the toaster should wrap the route tree. Mount it once either way.