SVoast v2.5.0

A simple toast component for Svelte

Features

  • SvelteKit and SSR compatible.
  • Zero Dependencies.
  • Built using TypeScript. All types are exported.
  • Themeing support using CSS variables.
  • Optional custom components.
  • Effortless setup. Import the component, use the function.

Installation

Install using your favourite package manager:

npm i svoast -D
yarn add svoast -D
pnpm add svoast -D

Usage

Import the <Toasts /> component to your main layout file.

svelte
<script>
import { Toasts } from 'svoast';
</script>
<Toasts />

And then call the toast function anywhere! (on the client, of course)

svelte
<script>
import { toast } from 'svoast';
async function launchToast() {
toast.success('Super good looking toast ;)');
}
</script>
<button on:click={launchToast}>Launch Toast</button>

Attention levels

You have 5 levels of toasts to play with.

Info, attention, success, warning, and error.
These should be enough to express to the user what they mean.
If not, check out the custom components docs where you can completely customize the look and functionality of your toasts.


Options

There are 4 options that you can pass:

  • closable will allow the user to dismiss the toast early.
  • duration well, will be the time the toast is visible.
  • infinite will ignore duration and will never be removed unless you give the user a dismiss button.
  • rich will render the message as a HTML string. So providing <strong>Warning</strong>: there was an error. will render the strong tags.

Positioning

The <Toasts /> component has a position prop that allows you to change what position the toasts are displayed from.
This will change what direction they popout from and how they stack on each other.


Styling

SVoast uses CSS variables.

css
:root {
/* Spacing for the container and between each toast */
--svoast-offset: 16px;
--svoast-gap: 16px;
/* The toast itself. */
--svoast-bg: #333;
--svoast-text: #fff;
--svoast-padding: 10px 15px 10px 18px;
--svoast-radius: 4px;
--svoast-shadow: 0 2px 7px hsl(0 0% 0% / 0.25);
--svoast-font-size: 14px;
--svoast-dismiss-gap: 8px;
--svoast-max-width: unset;
/* The current colour of the toast, depending on the type */
--svoast-colour: '';
/* Colour for each type */
--svoast-info-colour: #888;
--svoast-attention-colour: #38bdf8;
--svoast-success-colour: #4ade80;
--svoast-warning-colour: #fb923c;
--svoast-error-colour: #ef4444;
/* The coloured bar */
--svoast-bar-width: 3px;
/* Icons */
--svoast-icon-padding: 2px;
}

Promises

If you’re doing any api calls and want to alert to the user something is happening in the background, you can provide the promise type.

There are 3 required additional options:

  • loading is the text while the promise is pending.
  • success will be the text if the promise is resolved.
  • error is the text if the promise is rejected.
svelte
<script>
import { toast } from 'svoast';
import { db } from '$lib';
async function save() {
toast.promise(db.profile.save(), {
loading: 'Saving your profile...',
success: 'Profile updated!',
error: 'Something went wrong.'
});
}
</script>
<button on:click={save}>Save Profile</button>

Custom Components

If you want a completely new look and/or want to add functionality to the toasts, you can either do it globally or individually.

Global toasts

Providing a component to the component prop on the <Toasts /> component will overwrite the default toasts.
There’s a draw back to this though; you will be stuck with the props provided by this package.
View the API table below to see what the default props are.

svelte
<script>
import { Toasts } from 'svoast';
import Component from '$lib/Component.svelte';
</script>
<Toasts component={Component} />

Individual toasts

If you require to display a specific toast for an action, provide the component option on the toast call.
The first index of the array will be the custom component you want to use.
The second index of the array will be an object of any props you want to be passed down to your component.

NOTE: All props provided by this package are still passed down to your custom component (so no need to redefine everything).

svelte
<script>
// Default props from package:
export let id;
export let message;
export let type;
export let duration;
export let closable;
export let infinite;
// Custom props:
export let link;
export let newTab = false;
</script>
<div class="toast {type}" style="--duration: {duration}">
<p>{message}</p>
<a href={link} target={newTab ? '_blank' : undefined} rel={newTab ? 'noreferrer noopener' : undefined}> View Page </a>
</div>
svelte
<script>
import { toast } from 'svoast';
import LinkToast from '$lib/LinkToast.svelte';
async function save() {
toast.success('Successfully saved!', {
component: [LinkToast, { link: '/users/@me' }]
});
}
</script>
<button on:click={save}>Save Changes</button>

Custom dismiss button

If you want a dismiss button, make sure to export an id prop in your custom component.
And then you can use the removeById method on the toast function.

svelte
<script>
import { toast } from 'svoast';
export let id;
export let message;
</script>
<div>
{message}
<button on:click={() => toast.removeById(id)}>X</button>
</div>

Life cycle hooks

There are a number of hooks that you can use to run code when a certain action has happened.
For normal toasts, you have the onMount and onRemove methods.

For the promise toasts, you have the two mentioned before and onStart, onSuccess, onError, onFinish.
These should be pretty self-explanatory on when they run.

Simply pass these into the options object of your toast call.


API

Methods

Name Description
info Usually indicates information to the user, but isn’t important.
attention Indicate to the user with important information.
succcess Indicates to the user something good has happened.
warning Tell the user something may be wrong but isn’t critical.
error Alert the user something critical has happened.
promise Indicates to the user that something is happening in the background.
removeById Remove the toast by the unique ID.
removeByIndex Remove the toast by index position.
removeAll Remove all toasts.

Options

Property Type Description
closable boolean Allow the toast to be dismissed.
duration number | string The duration of the toast in milliseconds. After said time, the toast will remove itself.
component ToastCustomComponent Allow a custom component to be rendered.
infinite boolean Ignores duration and will never expire unless dismissed or removed by any of the remove methods.
rich boolean Allow the use of HTML in the message.
CAUTION: Make sure to sanitize ALL content provided by users.

Exported props

These are the props that are available to use if you wish to use a custom component.

Name Type
id number
type ToastType
message string
closable boolean
duration number | string
infinite boolean

Life Cycle Hooks

Name Parameters Type Description
onMount () => void When a toast has been added to the store.
onRemove () => void When a toast has been removed from the store.
onStart () => void When the promise has been started.
onSuccess data <T = any>(data: T) => void When the promise has been resolved.
onError data <T = any>(data: T) => void When the promise has been rejected.
onFinish () => void When the promise has ended, no matter the result.

Changelog

You can view all the changes HERE