toast

Toasts as a web component.

See a live demo

• Install
• API
  • ESM
  • Common JS
• Example
  • Example CSS
• Attributes
  • open
  • timeout
  • closable
  • timer
  • Variants
• Events
  • substrate-toast:show
  • substrate-toast:hide
• Methods
  • toast()
  • hide()
• CSS
  • Import CSS
  • CSS Variables
    • Layout & Typography
    • Primary Variant
    • Success Variant
    • Neutral Variant
    • Warning Variant
    • Danger Variant
    • CSS Variable Example
• Use
  • JS
  • HTML
  • pre-built
    • copy
    • HTML Example

Install

npm i -S @substrate-system/toast

API

This exposes ESM and common JS via package.json exports field.

ESM

import { SubstrateToast } from '@substrate-system/toast'

Common JS

const Toast = require('@substrate-system/toast')

Example

import '@substrate-system/toast'

// Create a toast element
const toast = document.createElement('substrate-toast')
toast.textContent = 'Operation completed successfully!'
toast.setAttribute('success', '')
toast.setAttribute('closable', '')
toast.setAttribute('timeout', '5000')
document.body.appendChild(toast)

// Show the toast
toast.toast()

Example CSS

Set the toast position to be center bottom (default is top right).

substrate-toast {
    position: fixed;
    left: 50%;
    bottom: 2rem;
    transform: translateX(-50%);
}

Attributes

open

Type: Boolean Default: false

Automatically displays the toast when the component is connected to the DOM.

<substrate-toast open>
    Message will show immediately
</substrate-toast>

timeout

Type: Number (milliseconds) Default: 3000

Controls how long the toast is displayed before automatically hiding. Set to 0 for infinite display (toast will not auto-hide).

<substrate-toast timeout="5000">Shows for 5 seconds</substrate-toast>

<substrate-toast timeout="0" closable>
    Shows until manually closed
</substrate-toast>

closable

Type: Boolean Default: false

Shows a close button that allows users to manually dismiss the toast.

<substrate-toast closable>
    Message with close button
</substrate-toast>

timer

Type: Boolean Default: true

Controls whether a visual countdown timer is displayed around the close button. The timer shows as a circular progress ring that shrinks clockwise as the timeout counts down. Only visible when closable is also enabled.

<!-- With countdown timer (default) -->
<substrate-toast closable timeout="5000">
    Message with visual timer
</substrate-toast>

<!-- Without countdown timer -->
<substrate-toast closable timeout="5000" timer="false">
    Message without visual timer
</substrate-toast>

Variants

Type: Boolean (mutually exclusive) Default: neutral Valid Values: primary, success, neutral, warning, danger

Determines the visual style and icon of the toast. Only one variant should be present.

| Variant | Icon | Use Case | |---------|------|----------| | primary | Info circle | General information/announcements | | success | Checkmark circle | Successful operations/confirmations | | neutral | Info circle | Neutral/default messages | | warning | Triangle alert | Warnings/cautions | | danger | X circle | Errors/failures |

<substrate-toast success>Operation successful!</substrate-toast>
<substrate-toast warning>Please review your settings.</substrate-toast>
<substrate-toast danger>An error occurred.</substrate-toast>
<substrate-toast primary>Information message.</substrate-toast>

Events

Use the static method .event to get namespaced event names for this component.

substrate-toast:show

Event Detail: { variant: ToastVariant }

Fired when the toast becomes visible (animation starts).

import { SubstrateToast } from '@substrate-system/toast'
const toast = document.querySelector('substrate-toast')

toast.addEventListener(SubstrateToast.event('show'), (ev) => {
  console.log('Toast showing with variant:', ev.detail.variant)
})

substrate-toast:hide

Event Detail: { variant: ToastVariant }

Fired when the toast is being hidden (either from timeout or manual close).

import { SubstrateToast } from '@substrate-system/toast'

const toast = document.querySelector('substrate-toast')
toast.addEventListener(SubstrateToast.event('hide'), (ev) => {
  console.log('Toast hidden with variant:', ev.detail.variant)
})

Methods

toast()

Display the toast by adding it to the queue and triggering the show animation. Toasts display sequentially - only one toast is visible at a time.

const toast = document.querySelector('substrate-toast')
toast.toast()

hide()

Hide the currently visible toast and process the next one in the queue.

const toast = document.querySelector('substrate-toast')
toast.hide()

CSS

Import CSS

import '@substrate-system/toast/css'

Or minified:

import '@substrate-system/toast/css/min'

CSS Variables

You can override these CSS variables:

Layout & Typography

• --toast-padding - Internal padding of the toast (default: 1rem)
• --toast-gap - Gap between icon, content, and close button (default: 0.75rem)
• --toast-font-size - Font size of toast content (default: 1rem)
• --toast-line-height - Line height of toast content (default: 1.5)
• --toast-max-width - Maximum width of the toast (default: 24rem)
• --toast-border - Border color (default: #0003)

Primary Variant

• --toast-primary-bg - Background color (default: #fff)
• --toast-primary-border - Left border color (default: #3b82f6)
• --toast-primary-text - Text color (default: #1e40af)
• --toast-primary-icon - Icon color (default: #3b82f6)

Success Variant

• --toast-success-bg - Background color (default: #fdfefd)
• --toast-success-border - Left border color (default: #10b981)
• --toast-success-text - Text color (default: #065f46)
• --toast-success-icon - Icon color (default: #10b981)

Neutral Variant

• --toast-neutral-bg - Background color (default: #f9fafb)
• --toast-neutral-border - Left border color (default: #6b7280)
• --toast-neutral-text - Text color (default: #374151)
• --toast-neutral-icon - Icon color (default: #6b7280)

Warning Variant

• --toast-warning-bg - Background color (default: #fbfaf6)
• --toast-warning-border - Left border color (default: #f59e0b)
• --toast-warning-text - Text color (default: #92400e)
• --toast-warning-icon - Icon color (default: #f59e0b)

Danger Variant

• --toast-danger-bg - Background color (default: #fff)
• --toast-danger-border - Left border color (default: #ef4444)
• --toast-danger-text - Text color (default: #991b1b)
• --toast-danger-icon - Icon color (default: #ef4444)

CSS Variable Example

substrate-toast {
    --toast-padding: 1.5rem;
    --toast-max-width: 30rem;
    --toast-success-bg: #e6f7ed;
    --toast-success-border: #22c55e;
}

Use

This calls the global function customElements.define. Just import, then use the tag in your HTML.

JS

The default timeout is 3 seconds. Set the time in milliseconds by passing in the timeout attribute.

import '@substrate-system/toast'

const el = document.querySelector('substrate-toast')

// programmatically show the toast
el?.toast()

HTML

<div>
    <substrate-toast timeout="4000">abc 123</substrate-toast>
</div>

pre-built

This package exposes minified JS and CSS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.

copy

cp ./node_modules/@substrate-system/toast/dist/index.min.js ./public/substrate-toast.min.js
cp ./node_modules/@substrate-system/toast/dist/style.min.css ./public/substrate-toast.css

HTML Example

<head>
    <link rel="stylesheet" href="./substrate-toast.css">
</head>
<body>
    <!-- ... -->
    <script type="module" src="./substrate-toast.min.js"></script>
</body>