SVoast v3.0.2

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.

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

<Toasts />

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

<script>
	import { toast } from 'svoast';

	async function launchToast() {
		toast.success('Super good looking toast ;)');
	}
</script>

<button onclick={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.

: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.
<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 onclick={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.

<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).

<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>
<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 onclick={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.

<script>
	import { toast } from 'svoast';

	export let id;
	export let message;
</script>

<div>
	{message}
	<button onclick={() => 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

NameDescription
infoUsually indicates information to the user, but isn’t important.
attentionIndicate to the user with important information.
succcessIndicates to the user something good has happened.
warningTell the user something may be wrong but isn’t critical.
errorAlert the user something critical has happened.
promiseIndicates to the user that something is happening in the background.
removeByIdRemove the toast by the unique ID.
removeByIndexRemove the toast by index position.
removeAllRemove all toasts.

Options

PropertyTypeDescription
closablebooleanAllow the toast to be dismissed.
durationnumber | stringThe duration of the toast in milliseconds. After said time, the toast will remove itself.
componentToastCustomComponentAllow a custom component to be rendered.
infinitebooleanIgnores duration and will never expire unless dismissed or removed by any of the remove methods.
richbooleanAllow 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.

NameType
idnumber
typeToastType
messagestring
closableboolean
durationnumber | string
infiniteboolean

Life Cycle Hooks

NameParametersTypeDescription
onMount() => voidWhen a toast has been added to the store.
onRemove() => voidWhen a toast has been removed from the store.
onStart() => voidWhen the promise has been started.
onSuccessdata<T = any>(data: T) => voidWhen the promise has been resolved.
onErrordata<T = any>(data: T) => voidWhen the promise has been rejected.
onFinish() => voidWhen the promise has ended, no matter the result.

Changelog

You can view all the changes HERE