Skip to main content

Toast

A succinct message that is displayed temporarily.

Features

  • Automatically closes
  • Pause closing on hover (single, all, none)

Anatomy

  • Content: Container for the content within the toast
  • Title: The title of the toast
  • Description: The description which supports the title
  • Close: The button(s) that close the toast

Usage

Unlike most builders, the toast is not component-based. Instead, it provides a global functionality that can be accessed from anywhere in your application. To accomplish this, it is recommended that you create a global component that is called on the root of your application.

The first step is to create a Toaster component that will be used to render toast notifications. We can take advantage of Svelte context module to create the template for the toast notifications and expose the helper function so it can be used in other components.

    <script lang="ts" context="module">
  export type ToastData = {
    title: string
    description: string
    color: string
  }
 
  const {
    elements: { content, title, description, close },
    helpers,
    states: { toasts },
    actions: { portal }
  } = createToaster<ToastData>()
 
  export const addToast = helpers.addToast
</script>
 
<script lang="ts">
  import { createToaster, melt } from '@melt-ui/svelte'
</script>
 
<div use:portal>
  {#each $toasts as { id, data } (id)}
    <div use:melt={$content(id)}>
      <div>
        <div>
          <h3 use:melt={$title(id)}>
            {data.title}
            <span style:color={data.color} />
          </h3>
          <div use:melt={$description(id)}>
            {data.description}
          </div>
        </div>
        <button use:melt={$close(id)} aria-label="close notification"> X </button>
      </div>
    </div>
  {/each}
</div>
	
    <script lang="ts" context="module">
  export type ToastData = {
    title: string
    description: string
    color: string
  }
 
  const {
    elements: { content, title, description, close },
    helpers,
    states: { toasts },
    actions: { portal }
  } = createToaster<ToastData>()
 
  export const addToast = helpers.addToast
</script>
 
<script lang="ts">
  import { createToaster, melt } from '@melt-ui/svelte'
</script>
 
<div use:portal>
  {#each $toasts as { id, data } (id)}
    <div {...$content(id)} use:content>
      <div>
        <div>
          <h3 {...$title(id)} use:title>
            {data.title}
            <span style:color={data.color} />
          </h3>
          <div {...$description(id)} use:description>
            {data.description}
          </div>
        </div>
        <button {...$close(id)} use:close aria-label="close notification"> X </button>
      </div>
    </div>
  {/each}
</div>

This component should be added to your root +layout.svelte or App.svelte component.

    <script>
  import Toaster from '$lib/Toaster.svelte'
</script>
 
<Toaster />
 
<slot />
	
    <script>
  import Toaster from '$lib/Toaster.svelte'
</script>
 
<Toaster />
 
<slot />

Finally, you can use the exported addToast helper function to add a toast from any component of the application.

    <script lang="ts">
  import { addToast } from '$lib/Toaster.svelte'
 
  function create() {
    addToast({
      data: {
        title: 'Success',
        description: 'The resource was created!',
        color: 'green'
      }
    })
  }
</script>
 
<button on:click={create}> Create </button>
	
    <script lang="ts">
  import { addToast } from '$lib/Toaster.svelte'
 
  function create() {
    addToast({
      data: {
        title: 'Success',
        description: 'The resource was created!',
        color: 'green'
      }
    })
  }
</script>
 
<button on:click={create}> Create </button>

Overriding default values for individual toasts

While you can define some global values for the Toaster on initialization, it is possible to override these defaults for individual toasts using the addToast helper function.

    <script lang="ts">
  const { helpers } = createToaster({
    closeDelay: 5000, // defaults to 5000
    type: 'background' // defaults to 'background'
  })
 
  // an example using the default values
  function create() {
    addToast({
      data
    })
  }
 
  // an example overriding the default values
  function createImportant() {
    addToast({
      data,
      closeDelay: 10000, // override the default closeDelay
      type: 'foreground' // override the default type
    })
  }
</script>
 
<button on:click={create}> Create </button>
 
<button on:click={createImportant}> Create Important </button>
	
    <script lang="ts">
  const { helpers } = createToaster({
    closeDelay: 5000, // defaults to 5000
    type: 'background' // defaults to 'background'
  })
 
  // an example using the default values
  function create() {
    addToast({
      data
    })
  }
 
  // an example overriding the default values
  function createImportant() {
    addToast({
      data,
      closeDelay: 10000, // override the default closeDelay
      type: 'foreground' // override the default type
    })
  }
</script>
 
<button on:click={create}> Create </button>
 
<button on:click={createImportant}> Create Important </button>

Example Components

With Progress

Each individual toast item provides a getPercentage helper function to determine the percentage of the time elapsed at any given moment. You can use that to provide a progress bar to your toasts

API Reference

createToaster

The builder function used to create the toast component.

Props

Prop Default Type / Description
closeDelay 5000
number

The delay in milliseconds before the toast closes. Set to 0 to disable.
type 'foreground'
'foreground' | 'background'

The sensitivity of the toast for accessibility purposes.
hover 'pause'
'pause' | 'pause-all' | null

The behavior when a toast is hovered.

Elements

Element Description

The builder store used to create the toast description.

The builder store used to create the toast title.

The builder store used to create the toast description.

The builder store used to create the toast close button.

States

State Description
toasts

A readable store that contains the open toasts.

Helpers

Helper Description
addToast

A helper function to add a toast to the toasts store.
removeToast

A helper function to remove a toast from the toasts store.
updateToast

A helper function to update a toast's data in the toasts store.

Actions

Action Description
portal

A portal action that renders the toasts into the body.

Options

Option Description
closeDelay

The delay in milliseconds before the toast closes. Set to 0 to disable.
type

The sensitivity of the toast for accessibility purposes.
hover

The behavior when a toast is hovered.

content

The description of the toast. Used for accessibility purposes.

Data Attributes

Data Attribute Value
[data-melt-toast-content]

Present on all content elements.

Custom Events

Event Value
m-pointerenter (e: ) => void
m-pointerleave (e: ) => void
m-focusout (e: ) => void

title

The title of the toast. Used for accessibility purposes.

Data Attributes

Data Attribute Value
[data-melt-toast-title]

Present on all title elements.

description

The description of the toast. Used for accessibility purposes.

Data Attributes

Data Attribute Value
[data-melt-toast-description]

Present on all description elements.

close

The element which closes the toast when clicked or pressed.

Data Attributes

Data Attribute Value
[data-melt-toast-close]

Present on all close elements.

Custom Events

Event Value
m-click (e: ) => void
m-keydown (e: ) => void

Accessibility

Adheres to the Alert WAI-ARIA design pattern

Key Behavior
Tab

Moves focus to the next focusable element within the toast.