README
svelte-toast
Simple elegant toast notifications.
A lightweight, unopinionated and performant toast notification component for modern web frontends in very little lines of code. Compiled, it's only 15kb minified (6kb gzipped) and can be used in Vanilla JS, or as a Svelte component.
Because a demo helps better than a thousand API docs: https://zerodevx.github.io/svelte-toast/
Usage
Install the package:
$ npm i -D @zerodevx/svelte-toast
The following are exported:
SvelteToast
as the toast container;toast
as the toast emitter.
Svelte
If you're using this in a Svelte app, import the toast container and place it in your app shell.
App.svelte
:
<script>
import { SvelteToast } from '@zerodevx/svelte-toast'
// Optionally set default options here
const options = {
...
}
</script>
...
<SvelteToast {options} />
Use anywhere in your app - just import the toast emitter.
MyComponent.svelte
:
<script>
import { toast } from '@zerodevx/svelte-toast'
</script>
<button on:click={() => toast.push('Hello world!')}>EMIT TOAST</button>
Vanilla JS
For any other application with a bundler, something like this should work:
import { SvelteToast, toast } from '@zerodevx/svelte-toast'
const app = new SvelteToast({
// Set where the toast container should be appended into
target: document.body,
props: {
options: {
// Optionally set default options here
...
}
}
})
toast.push('Hello world!')
CDN
Or if you prefer to go old-school javascript and a CDN:
<head>
...
<!-- Load `toast` and `SvelteToast` into global scope -->
<script src="https://cdn.jsdelivr.net/npm/@zerodevx/svelte-toast@0"></script>
<!-- Register the app -->
<script>
const toastApp = new SvelteToast({
// Set where the toast container should be appended into
target: document.body,
props: {
options: {
// Optionally set default options here
...
}
}
})
// Now you can `toast` anywhere!
toast.push('Hello world!');
</script>
</head>
Theming
In general, use CSS variables - the following (self-explanatory) vars are exposed:
._toastContainer {
top: var(--toastContainerTop, 1.5rem);
right: var(--toastContainerRight, 2rem);
bottom: var(--toastContainerBottom, auto);
left: var(--toastContainerLeft, auto);
}
._toastItem {
width: var(--toastWidth, 16rem);
height: var(--toastHeight, auto);
min-height: var(--toastMinHeight, 3.5rem);
margin: var(--toastMargin, 0 0 0.5rem 0);
background: var(--toastBackground, rgba(66,66,66,0.9));
color: var(--toastColor, #FFF);
box-shadow: var(--toastBoxShadow, 0 4px 6px -1px rgba(0,0,0,0.1),0 2px 4px -1px rgba(0,0,0,0.06));
border-radius: var(--toastBorderRadius, 0.125rem);
}
._toastMsg {
padding: var(--toastMsgPadding, 0.75rem 0.5rem);
}
._toastProgressBar {
background: var(--toastProgressBackground, rgba(33,150,243,0.75));
}
So to apply your custom theme globally, do something like:
<style>
:root {
--toastBackground: #ABCDEF;
--toastColor: #123456;
--toastHeight: 300px;
...
}
</style>
To apply CSS overrides to a particular Toast Item (on a per-toast basis), emit the toast with options:
toast.push('Yo!', {
theme: {
'--toastBackground': 'cyan',
'--toastColor': 'black',
...
}
})
where theme
is an object containing one or more CSS var key/value pairs.
Create Your Own Toast Actions
For convenient composing, the recommended way is to create your own common toast actions by stubbing them out. For example:
my-theme.js
import { toast } from '@zerodevx/svelte-toast'
export const success = m => toast.push(m, {
theme: {
'--toastBackground': 'green',
'--toastColor': 'white',
'--toastProgressBackground': 'darkgreen'
}
})
export const warning = m => toast.push(m, { theme: { ... } })
export const failure = m => toast.push(m, { theme: { ... } })
Then simply import these stubs in your consuming component:
import { success, warning, failure } from './my-theme'
// do something, then
success('It works!')
Rich HTML
Toast messages can be in rich HTML too - for example:
// Definitely not spam
toast.push(`<strong>You won the jackpot!</strong><br>
Click <a href="#" target="_blank">here</a> for details! 😛`)
Custom Fonts
In a Svelte app, the easiest way to apply custom font styles is to wrap the toast container then apply styles on the wrapper:
<style>
.wrap {
font-family: Roboto, sans-serif;
font-size: 0.875rem;
...
}
.wrap :global(strong) {
font-weight: 600;
}
</style>
<div class="wrap">
<SvelteToast />
</div>
In Vanilla JS, simply apply your styles to the ._toastMsg
class:
._toastMsg {
font-family: Roboto, sans-serif;
...
}
v0.4
New from Supporting Multiple Toast Containers
It's now easy to send toasts to different container targets within your app. For example:
<script>
import { SvelteToast, toast } from '@zerodevx/svelte-toast'
// Sends a toast to default toast container
toast.push('Yo!')
// Sends a toast to "new" toast container
toast.push('Hey!', { target: 'new' })
</script>
<style>
.wrap {
--toastContainerTop: 0.5rem;
--toastContainerRight: 2rem;
--toastContainerBottom: auto;
--toastContainerLeft: 2rem;
--toastWidth: 100%;
font-size: 0.875rem;
...
}
</style>
<!-- Default toast container -->
<SvelteToast />
<!-- Another toast container -->
<div class="wrap">
<!-- Declare container with a unique `target` name -->
<SvelteToast target="new" options={{ duration: 8000, intro: { y: -64 } }} />
</div>
Removing Multiple Toasts
pop()
now accepts a filter function.
// Remove all toasts from "new" container
toast.pop(i => i.target !== 'new')
// Or remove ALL active toasts from ALL containers
toast.pop(0)
Accepts Object as First Param
push()
and set()
can also take an object as its first parameter.
let id = toast.push('Yo!', { duration: 2000 })
// is semantically equivalent to
id = toast.push({ msg: 'Yo!', duration: 2000 })
toast.set(id, { msg: 'Waddup!' })
// is semantically equivalent to
toast.set({ id, msg: 'Waddup!' })
Options
// Default options
const options = {
duration: 4000, // duration of progress bar tween
dismissable: true, // allow dismiss with close button
initial: 1, // initial progress bar value
progress: 0, // current progress
reversed: false, // insert new toast to bottom of stack
intro: { x: 256 }, // toast intro fly animation settings
theme: {} // css var overrides
}
Toast API
const id = toast.push(message, { options })
toast.pop(id)
toast.set(id, { options })
Development
Standard Github contribution workflow applies.
Tests
Testing is through Cypress. To run the tests headlessly:
$ npm run test
Changelog
Please refer to the releases page.
License
ISC