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 ignoreduration
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 thestrong
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
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