Toast

Show notifications with actions, timed dismissal, and screen reader announcements.

A toast tells someone that something happened, like a saved change or a sent message, and goes away on its own. It can offer an action such as Undo, stacks with the toasts before it, and is announced to screen readers without taking focus.

Console

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { log } from "./log"

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <button>Create Event</button>
    <ui-toast-region>
      <template>
        <ui-toast>
          <div data-slot="stack">
            <ui-toast-title></ui-toast-title>
            <ui-toast-description></ui-toast-description>
          </div>
          <ui-toast-action><button data-variant="solid"></button></ui-toast-action>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  root.querySelector("button")!.addEventListener("click", () =>
    toast("Event created", {
      description: "Friday, June 12 at 10:00 AM",
      action: { label: "Undo", onAction: () => log(root, "Event removed") },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Create Event. Choose Undo, swipe the toast away, or wait for it to close. Undo logs Event removed.

Installation

npm install @ui-sdk/web @ui-sdk/core

Import the component to register its elements. The import is safe on the server.

import "@ui-sdk/web/toast"

Composition

Use the following composition to build a ui-toast-region:

ui-toast-region
└── template
    └── ui-toast
        ├── ui-toast-title
        ├── ui-toast-description
        ├── ui-toast-action
        │   └── button
        └── ui-toast-close
            └── button

The region clones the ui-toast in its template for each toast in its queue, newest first. A toast is named by its title and described by its description. Empty title, description and action parts show the text from the toast's data, so a region's template is usually the same few parts. An empty ui-toast-close shows the toast's cancel and runs its onCancel, and hides when the toast has none.

Usage

Import the parts and put them together, then call toast() when an action finishes:

<script type="module">
  import "@ui-sdk/web/toast"
  import { toast } from "@ui-sdk/web"

  document
    .querySelector("#create-event")
    .addEventListener("click", () =>
      toast("Event created", { description: "Friday at 10:00 AM" })
    )
</script>

<button id="create-event" type="button">Create Event</button>
<ui-toast-region>
  <template>
    <ui-toast>
      <ui-toast-title></ui-toast-title>
      <ui-toast-description></ui-toast-description>
    </ui-toast>
  </template>
</ui-toast-region>

toast() works from anywhere, not only from event listeners, and returns the toast's id. Place the region once, near your app's root. Without a template, it renders each toast's title, description, action and cancel button with unstyled parts.

The examples below each call createToaster() for a queue of their own and set it on their region's toaster property, so their toasts don't mix.

Types

toast.success, .info, .warning, .error and .loading set the toast's type, which the toast exposes as data-type for an icon or a color. Errors are announced right away and other types wait for a pause; set priority to change that. A loading toast stays until it's updated or dismissed.

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import {
  CircleCheck,
  createElement,
  Info,
  LoaderCircle,
  OctagonX,
  TriangleAlert,
} from "lucide"

const upload = () => new Promise((resolve) => setTimeout(resolve, 2000))

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <div data-slot="row">
      <button>Default</button>
      <button>Success</button>
      <button>Info</button>
      <button>Warning</button>
      <button>Error</button>
      <button>Loading</button>
    </div>
    <ui-toast-region>
      <template>
        <ui-toast>
          ${createElement(CircleCheck, { "data-show": "success", "aria-hidden": "true" }).outerHTML}
          ${createElement(Info, { "data-show": "info", "aria-hidden": "true" }).outerHTML}
          ${createElement(TriangleAlert, { "data-show": "warning", "aria-hidden": "true" }).outerHTML}
          ${createElement(OctagonX, { "data-show": "error", "aria-hidden": "true" }).outerHTML}
          ${createElement(LoaderCircle, { "data-show": "loading", "aria-hidden": "true" }).outerHTML}
          <ui-toast-title></ui-toast-title>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  const [plain, success, info, warning, error, loading] =
    root.querySelectorAll("button")
  plain.addEventListener("click", () => toast("Event created"))
  success.addEventListener("click", () => toast.success("Changes saved"))
  info.addEventListener("click", () => toast.info("A new version is available"))
  warning.addEventListener("click", () =>
    toast.warning("Storage is almost full")
  )
  error.addEventListener("click", () => toast.error("Couldn't save changes"))
  loading.addEventListener("click", () =>
    toast.promise(upload, {
      loading: "Uploading photos…",
      success: "Photos uploaded",
      error: "Upload failed",
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Choose a type. Each toast shows its type's icon, and Loading turns into Photos uploaded when it finishes.

Position

Set the region's side to top or bottom, and align to start, center or end. Start and end follow the writing direction. A toast can be swiped toward the side and, unless it's centered, toward the end it's aligned to.

import "@ui-sdk/web/select"
import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { Check, ChevronDown, createElement } from "lucide"

const sides = [
  { value: "top", label: "Top" },
  { value: "bottom", label: "Bottom" },
]
const aligns = [
  { value: "start", label: "Start" },
  { value: "center", label: "Center" },
  { value: "end", label: "End" },
]

const check = createElement(Check, { "aria-hidden": "true" }).outerHTML
const chevron = createElement(ChevronDown, { "aria-hidden": "true" }).outerHTML

function select(
  attribute: string,
  label: string,
  value: string,
  options: { value: string; label: string }[]
) {
  return `
    <ui-select data-attribute="${attribute}" default-value="${value}">
      <ui-select-label>${label}</ui-select-label>
      <ui-select-trigger>
        <button>
          <ui-select-value></ui-select-value>
          ${chevron}
        </button>
      </ui-select-trigger>
      <ui-select-content hidden>
        ${options
          .map(
            (option) => `
              <ui-select-item value="${option.value}">
                ${option.label}
                <ui-select-item-indicator>${check}</ui-select-item-indicator>
              </ui-select-item>
            `
          )
          .join("")}
      </ui-select-content>
    </ui-select>
  `
}

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <div data-slot="stack">
      <div data-slot="controls">
        ${select("side", "Side", "bottom", sides)}
        ${select("align", "Align", "end", aligns)}
      </div>
      <button>Create Event</button>
      <ui-toast-region side="bottom" align="end">
        <template>
          <ui-toast>
            <div data-slot="stack">
              <ui-toast-title></ui-toast-title>
              <ui-toast-description></ui-toast-description>
            </div>
          </ui-toast>
        </template>
      </ui-toast-region>
    </div>
  `
  const region = root.querySelector("ui-toast-region")!
  region.toaster = toast
  for (const control of root.querySelectorAll("ui-select")) {
    control.addEventListener("valuechange", (event) => {
      const value = event.detail.value
      if (typeof value === "string") {
        region.setAttribute(control.dataset.attribute!, value)
      }
    })
  }
  root
    .querySelector("[data-slot='controls'] + button")!
    .addEventListener("click", () =>
      toast("Event created", { description: "Friday, June 12 at 10:00 AM" })
    )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Choose a side and an alignment, then press Create Event and look for the toast at that edge of the page.

Action and Cancel

Add an action, like Undo, and a cancel button that dismisses the toast. Their callbacks can update your app. onDismiss tells you why the toast is closing, and details.cancel() keeps it open; a canceled timeout starts the countdown again.

Console

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { log } from "./log"

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <button>Archive Message</button>
    <ui-toast-region>
      <template>
        <ui-toast>
          <ui-toast-title></ui-toast-title>
          <ui-toast-close><button></button></ui-toast-close>
          <ui-toast-action><button data-variant="solid"></button></ui-toast-action>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  root.querySelector("button")!.addEventListener("click", () =>
    toast("Message archived", {
      action: { label: "Undo", onAction: () => log(root, "Message restored") },
      cancel: { label: "Dismiss", onCancel: () => log(root, "Kept archived") },
      onDismiss: ({ reason }) => log(root, `Closed (${reason})`),
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Archive Message, then choose Undo or Dismiss, swipe the toast away, or let it time out. The console logs why it closed.

Link

Give an action an href, and write an <a> in ui-toast-action instead of a <button> to render it as a link; the region's renderToast sets the link's href from the toast. It keeps normal link behavior, including opening in a new tab.

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <button>Send Invoice</button>
    <ui-toast-region>
      <template>
        <ui-toast>
          <div data-slot="stack">
            <ui-toast-title></ui-toast-title>
            <ui-toast-description></ui-toast-description>
          </div>
          <ui-toast-action><a data-variant="solid"></a></ui-toast-action>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  const region = root.querySelector("ui-toast-region")!
  region.toaster = toast
  region.renderToast = (item, el) => {
    if (item.action?.href) {
      el.querySelector("a")!.href = item.action.href
    }
  }
  root.querySelector("button")!.addEventListener("click", () =>
    toast("Invoice sent", {
      description: "Hollis Grant · $240.00",
      action: { label: "View", href: "#" },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Send Invoice, then follow View in the toast.

Promise

toast.promise() shows a loading toast, then updates the same toast when the promise resolves or rejects. Each message can be a string, options with a description or an action, or a function of the result. A toast dismissed while loading stays closed.

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"

function mount(root: HTMLElement) {
  const toast = createToaster()
  let attempts = 0

  function save() {
    const succeeds = ++attempts % 2 === 1
    return new Promise<void>((resolve, reject) =>
      setTimeout(
        () => (succeeds ? resolve() : reject(new Error("Network error"))),
        1500
      )
    )
  }

  function saveChanges() {
    toast.promise(save, {
      loading: "Saving changes…",
      success: "Changes saved",
      error: {
        title: "Couldn't save changes",
        description: "Check your connection and try again.",
        action: { label: "Retry", onAction: saveChanges },
      },
    })
  }

  root.innerHTML = `
    <button>Save Changes</button>
    <ui-toast-region>
      <template>
        <ui-toast>
          <div data-slot="stack">
            <ui-toast-title></ui-toast-title>
            <ui-toast-description></ui-toast-description>
          </div>
          <ui-toast-action><button data-variant="solid"></button></ui-toast-action>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  root.querySelector("button")!.addEventListener("click", saveChanges)
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Save Changes to see Saving changes become Changes saved. Press it again for the error, then choose Retry.

Stacking

max-visible limits how many toasts show at once, three by default; the rest wait in the queue, and their timers start when they show. The stack expands while the pointer or focus is in it. Set expanded to keep it open. Styling shows the CSS that lays out the stack.

import "@ui-sdk/web/checkbox"
import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { Check, createElement } from "lucide"

const notifications = [
  { title: "Event created", description: "Friday, June 12 at 10:00 AM" },
  { title: "Message sent" },
  {
    title: "Hollis Grant joined",
    description: "They can now edit the Launch plan and see its comments.",
  },
  { title: "Changes saved" },
  { title: "Invoice sent", description: "Inès Moreau · $240.00" },
  { title: "Photos uploaded", description: "12 photos added to Summer trip" },
]

function mount(root: HTMLElement) {
  const toast = createToaster()
  let count = 0
  root.innerHTML = `
    <div data-slot="stack">
      <div data-slot="controls">
        <label data-slot="label">
          <ui-checkbox>
            <ui-checkbox-indicator>${createElement(Check, { "aria-hidden": "true" }).outerHTML}</ui-checkbox-indicator>
          </ui-checkbox>
          Always expanded
        </label>
      </div>
      <button>Add Toast</button>
      <ui-toast-region max-visible="4">
        <template>
          <ui-toast>
            <div data-slot="stack">
              <ui-toast-title></ui-toast-title>
              <ui-toast-description></ui-toast-description>
            </div>
          </ui-toast>
        </template>
      </ui-toast-region>
    </div>
  `
  const region = root.querySelector("ui-toast-region")!
  region.toaster = toast
  root
    .querySelector("ui-checkbox")!
    .addEventListener("checkedchange", (event) => {
      region.expanded = event.detail.value === true
    })
  root
    .querySelector("button")!
    .addEventListener("click", () =>
      toast(notifications[count++ % notifications.length])
    )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Add Toast a few times, then hover the stack to expand it. Past four toasts, the rest wait their turn. Check Always expanded to keep it open.

Duration

Set duration in milliseconds, on the toaster or on one toast, or Infinity for a toast that stays until it's dismissed. The default is five seconds. Timers pause while the pointer or focus is in the region, and while the page is hidden or its window is inactive.

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <div data-slot="row">
      <button>1 Second</button>
      <button>5 Seconds</button>
      <button>Until Dismissed</button>
    </div>
    <ui-toast-region>
      <template>
        <ui-toast>
          <ui-toast-title></ui-toast-title>
          <ui-toast-close><button data-variant="solid"></button></ui-toast-close>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  const [second, seconds, untilDismissed] = root.querySelectorAll("button")
  second.addEventListener("click", () =>
    toast("Link copied", { duration: 1000 })
  )
  seconds.addEventListener("click", () => toast("Changes saved"))
  untilDismissed.addEventListener("click", () =>
    toast("Your session expires in 5 minutes", {
      duration: Infinity,
      dismissible: false,
      cancel: { label: "Got It" },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press each button. Hover a toast to pause its timer. The session toast stays until you press Got It.

Update and Dismiss

Keep the id toast() returns to update or dismiss that toast, or pass your own id. toast.update() returns whether the toast was still there, and toast.dismiss() without an id closes every toast.

Console

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { CircleCheck, createElement, LoaderCircle } from "lucide"
import { log } from "./log"

function mount(root: HTMLElement) {
  const toast = createToaster()
  let timer: ReturnType<typeof setInterval> | undefined

  function upload() {
    clearInterval(timer)
    const id = toast.loading("Uploading report.pdf… 0%", { id: "upload" })
    let progress = 0
    timer = setInterval(() => {
      progress += 20
      const done = progress >= 100
      const open = toast.update(
        id,
        done
          ? { title: "Report uploaded", type: "success" }
          : { title: `Uploading report.pdf… ${progress}%` }
      )
      if (!open) {
        log(root, "Upload canceled")
      }
      if (done || !open) {
        clearInterval(timer)
      }
    }, 700)
  }

  root.innerHTML = `
    <div data-slot="row">
      <button>Upload Report</button>
      <button>Cancel Upload</button>
      <button>Dismiss All</button>
    </div>
    <ui-toast-region>
      <template>
        <ui-toast>
          ${createElement(CircleCheck, { "data-show": "success", "aria-hidden": "true" }).outerHTML}
          ${createElement(LoaderCircle, { "data-show": "loading", "aria-hidden": "true" }).outerHTML}
          <ui-toast-title></ui-toast-title>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  const [start, cancel, dismissAll] = root.querySelectorAll("button")
  start.addEventListener("click", upload)
  cancel.addEventListener("click", () => toast.dismiss("upload"))
  dismissAll.addEventListener("click", () => toast.dismiss())
  return () => {
    clearInterval(timer)
    toast.dismiss()
  }
}

export { mount }

Press Upload Report and watch one toast count up to Report uploaded. Cancel Upload closes it early, and Dismiss All clears every toast.

Async Action

Return a promise from an action to keep the toast open while it runs. Its button gets data-pending while it runs and ignores presses until it settles, and the action can change the button's text to say Restoring…, or offer a retry if it fails. See Button for changes made after an await.

Console

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { log } from "./log"

const restore = () => new Promise((resolve) => setTimeout(resolve, 1500))

function mount(root: HTMLElement) {
  const toast = createToaster({ duration: 6000 })
  root.innerHTML = `
    <button>Delete File</button>
    <ui-toast-region>
      <template>
        <ui-toast>
          <div data-slot="stack">
            <ui-toast-title></ui-toast-title>
            <ui-toast-description></ui-toast-description>
          </div>
          <ui-toast-action><button data-variant="solid"></button></ui-toast-action>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  root.querySelector("button")!.addEventListener("click", () =>
    toast("File deleted", {
      description: "Q3 report.pdf",
      action: {
        label: "Undo",
        onAction: async (event) => {
          const button = (event?.target as Element | undefined)?.closest(
            "button"
          )
          if (button) {
            button.textContent = "Restoring…"
          }
          try {
            await restore()
          } catch (error) {
            if (button) {
              button.textContent = "Retry"
            }
            throw error
          }
          log(root, "Q3 report.pdf restored")
        },
      },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Delete File, then Undo. The button shows Restoring… until the restore finishes, then the toast closes.

Keyboard Shortcut

F6 moves focus to the newest toast and back. Set the region's shortcut to use another key, or none to turn it off. The region advertises it through aria-keyshortcuts.

Console

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { log } from "./log"

function mount(root: HTMLElement) {
  const toast = createToaster({ duration: 10000 })
  root.innerHTML = `
    <button>Send Message</button>
    <ui-toast-region shortcut="alt+t" aria-label="Alerts">
      <template>
        <ui-toast>
          <ui-toast-title></ui-toast-title>
          <ui-toast-action><button data-variant="solid"></button></ui-toast-action>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  root.querySelector("ui-toast-region")!.toaster = toast
  root.querySelector("button")!.addEventListener("click", () =>
    toast("Message sent", {
      action: { label: "Undo", onAction: () => log(root, "Message unsent") },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Send Message, then Alt+T (Option+T on a Mac) to focus the toast. Press Escape to dismiss it, or Alt+T again to go back.

Overlay Host and Confirm

Instead of placing a region, add one ui-overlay-host near your app's root. It renders the toaster's region and confirm() questions as alert dialogs. Set its toast property before it connects: attributes go on the region, and template holds the ui-toast each toast copies. A region you place yourself takes over from the host for its toaster.

To style the question, render a ui-alert-dialog with the confirm controller and read the question from its payloadchange event. Alert Dialog covers createConfirm() in more detail.

import "@ui-sdk/web/alert-dialog"
import "@ui-sdk/web/overlays"
import {
  createConfirm,
  createOverlays,
  createToaster,
  type ConfirmOptions,
  type UiAlertDialogElement,
} from "@ui-sdk/web"
import { CircleCheck, createElement } from "lucide"

const names = ["Acme", "Globex", "Initech"]

function mount(root: HTMLElement) {
  const overlays = createOverlays()
  const toast = createToaster({ overlays })
  const confirm = createConfirm({ overlays })
  let projects = names
  root.innerHTML = `
    <div data-slot="stack">
      <div data-slot="controls">
        <button type="button">Reset Projects</button>
      </div>
      <ul data-slot="list" aria-label="Projects"></ul>
      <ui-alert-dialog>
        <ui-alert-dialog-backdrop hidden></ui-alert-dialog-backdrop>
        <ui-alert-dialog-content hidden>
          <div data-slot="stack">
            <ui-alert-dialog-title></ui-alert-dialog-title>
            <ui-alert-dialog-description></ui-alert-dialog-description>
          </div>
          <div data-slot="row">
            <ui-alert-dialog-close><button></button></ui-alert-dialog-close>
            <ui-alert-dialog-close value="confirm"><button data-variant="solid"></button></ui-alert-dialog-close>
          </div>
        </ui-alert-dialog-content>
      </ui-alert-dialog>
    </div>
  `
  const reset = root.querySelector("button")!
  const list = root.querySelector("ul")!

  function render() {
    list.innerHTML = projects.length
      ? projects
          .map(
            (name) =>
              `<li data-slot="row">${name}<button type="button" data-size="sm" aria-label="Delete ${name}">Delete</button></li>`
          )
          .join("")
      : `<li data-slot="row">All projects deleted.</li>`
    list.querySelectorAll("button").forEach((button, index) => {
      const name = projects[index]
      button.addEventListener("click", () => remove(name, index))
    })
  }

  async function remove(name: string, index: number) {
    const confirmed = await confirm({
      title: `Delete ${name}?`,
      description:
        "The project and its files will be deleted for everyone on your team.",
      confirmLabel: "Delete",
      cancelLabel: "Cancel",
    })
    if (!confirmed) {
      return
    }
    projects = projects.filter((project) => project !== name)
    render()
    ;(
      list.querySelectorAll("button")[Math.min(index, projects.length - 1)] ??
      reset
    ).focus()
    toast.success(`${name} deleted`, { priority: "assertive" })
  }

  reset.addEventListener("click", () => {
    projects = names
    render()
  })
  render()

  const dialog =
    root.querySelector<UiAlertDialogElement<ConfirmOptions>>("ui-alert-dialog")!
  const [cancel, agree] = dialog.querySelectorAll("button")
  dialog.controller = confirm.controller
  dialog.addEventListener("payloadchange", (event) => {
    const question = event.detail.value
    dialog.querySelector("ui-alert-dialog-title")!.textContent =
      question?.title ?? ""
    dialog.querySelector("ui-alert-dialog-description")!.textContent =
      question?.description ?? ""
    cancel.textContent = question?.cancelLabel ?? ""
    agree.textContent = question?.confirmLabel ?? ""
  })

  const template = document.createElement("template")
  template.innerHTML = `
    <ui-toast>
      ${createElement(CircleCheck, { "data-show": "success", "aria-hidden": "true" }).outerHTML}
      <ui-toast-title></ui-toast-title>
    </ui-toast>
  `
  dialog.before(
    Object.assign(document.createElement("ui-overlay-host"), {
      overlays,
      toast: { template },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press Delete on a project and confirm. The row goes away and a toast says so. Reset Projects brings them back.

Custom Rendering

Pass anything else your toast needs in data, and read it in the region's renderToast(toast, el), which runs for each toast element when it shows and after every update.

Console

import "@ui-sdk/web/toast"
import { createToaster } from "@ui-sdk/web"
import { createElement, X } from "lucide"
import { log } from "./log"

function mount(root: HTMLElement) {
  const toast = createToaster()
  root.innerHTML = `
    <button>New Message</button>
    <ui-toast-region aria-label="Messages">
      <template>
        <ui-toast>
          <span data-slot="media"></span>
          <div data-slot="stack">
            <ui-toast-title></ui-toast-title>
            <ui-toast-description></ui-toast-description>
          </div>
          <ui-toast-action><button data-variant="solid"></button></ui-toast-action>
          <ui-toast-close>
            <button aria-label="Close">${createElement(X, { "aria-hidden": "true" }).outerHTML}</button>
          </ui-toast-close>
        </ui-toast>
      </template>
    </ui-toast-region>
  `
  const region = root.querySelector("ui-toast-region")!
  region.toaster = toast
  region.renderToast = (item, el) => {
    el.querySelector("[data-slot='media']")!.textContent = (
      item.data as { initials: string }
    ).initials
  }
  root.querySelector("button")!.addEventListener("click", () =>
    toast({
      title: "Hollis Grant",
      description: "Can you review the draft?",
      data: { initials: "HG" },
      action: {
        label: "Reply",
        onAction: () => log(root, "Replying to Hollis Grant"),
      },
    })
  )
  return () => {
    toast.dismiss()
  }
}

export { mount }

Press New Message to show a toast with Hollis Grant's initials. Choose Reply or close it.

Styling

Toasts are unstyled, and the region and its toasts carry what you need to animate a stack:

The stack. The region sets --toast-front-height, the newest toast's height, and --toast-stack-height, all of them added up. Each toast gets --toast-index, 0 for the newest, --toast-offset, the height of the toasts in front of it, and --toast-height, its own height. Position the toasts absolutely in the region and set height: var(--toast-height) so changes in height animate.
Collapsed and expanded. data-front marks the newest toast. While the stack is collapsed, clip the toasts behind it to --toast-front-height and peek them out by their index. While it's expanded, the region and its toasts get data-expanded; move each toast by its --toast-offset.
Swiping. While a toast is swiped it gets data-swiping, and --toast-swipe-x and --toast-swipe-y hold how far it moved. Translate it by them and turn off transitions. When a swipe dismisses it, data-swipe-direction says which way, so it can leave in that direction. A mouse drag that starts on selectable text selects it, so set user-select: none on toasts to swipe them from anywhere.
Entering and leaving. A toast has data-starting-style for its first frame and data-ending-style while it leaves, and stays mounted until its transitions finish.

A stack at the bottom of the page, in plain CSS:

[data-slot="toast-region"] {
  width: 356px;
  height: var(--toast-front-height);
}

[data-slot="toast-region"][data-expanded] {
  height: calc(var(--toast-stack-height) + (var(--toast-count) - 1) * 12px);
}

[data-slot="toast"] {
  --y: calc(var(--toast-index) * -12px);
  position: absolute;
  inset-inline: 0;
  bottom: 0;
  z-index: calc(100 - var(--toast-index));
  overflow: hidden;
  height: var(--toast-height);
  translate: var(--toast-swipe-x, 0px)
    calc(var(--y) + var(--toast-swipe-y, 0px));
  scale: calc(1 - var(--toast-index) * 0.05);
  transition-property: translate, scale, opacity, height;
  transition-duration: 400ms;
  user-select: none;
}

[data-slot="toast"]:not([data-front], [data-expanded]) {
  height: var(--toast-front-height);
}

[data-slot="toast"][data-expanded] {
  --y: calc(-1 * (var(--toast-offset) + var(--toast-index) * 12px));
  scale: 1;
}

[data-slot="toast"][data-starting-style] {
  transition: none;
}

[data-slot="toast"][data-starting-style][data-front] {
  --y: 100%;
}

[data-slot="toast"]:is(
  [data-starting-style]:not([data-front]),
  [data-ending-style]
) {
  opacity: 0;
}

[data-slot="toast"][data-swiping] {
  transition: none;
}

@media (prefers-reduced-motion: reduce) {
  [data-slot="toast"] {
    transition-property: opacity;
  }
}

Each part has a data-slot, such as toast, and its state attributes are listed under Data Attributes. An action's or close's attributes land on its button.

`<ui-toast-region>`

Variable	What it holds
`--toast-front-height`	The newest toast's height. Clip the toasts behind it to it in a collapsed stack.
`--toast-stack-height`	The toasts' heights added up, for the height of an expanded stack.
`--toast-count`	How many toasts show.
`--keyboard-inset`	How many pixels of the page the on-screen keyboard covers, 0 without one.
`--visual-viewport-width`	The width of the part of the page you can see.
`--visual-viewport-height`	The height of the part of the page you can see, above the keyboard.
`--visual-viewport-top`	How far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up.

`<ui-toast>`

Variable	What it holds
`--toast-index`	The toast's place in the stack, 0 for the newest. A closing toast keeps its place.
`--toast-offset`	The height of the toasts in front of this one, in pixels. Add gaps with `--toast-index` to place an expanded stack.
`--toast-height`	The toast's own height with its content laid out freely, whatever height it's given. Set it as the height to animate the stack.
`--toast-swipe-x`	How far a swipe moved the toast sideways, in pixels. Translate the toast by it.
`--toast-swipe-y`	How far a swipe moved the toast up or down, in pixels.

Data Attributes

ui-toast-title and ui-toast-description have no state attributes. The button in ui-toast-close gets data-pending, like the one in ui-toast-action, while a Promise from its action runs.

`<ui-toast-region>`

[data-slot="toast-region"]

Attribute	What it means
`data-side`	`topbottom`The edge of the viewport the region sits on.
`data-align`	`startcenterend`Where along that edge.
`data-expanded`	Present while the stack is expanded: hovered, focused, or always with `expanded`.
`data-keyboard`	Present on the region while the on-screen keyboard covers part of the page.

`<ui-toast>`

[data-slot="toast"]

Attribute	What it means
`data-type`	`defaultsuccesserrorinfowarningloading`What the toast is about.
`data-front`	Present on the newest toast, in front of a collapsed stack. A closing toast keeps it while it animates out.
`data-expanded`	Present while the stack is expanded: hovered, focused, or always with `expanded`.
`data-starting-style`	Present for a toast's first frame. Style the state you animate from.
`data-ending-style`	Present while a toast animates out. Style the state you animate to.

`<ui-toast-action>`

[data-slot="toast-action"]

Attribute	What it means
`data-pending`	Present on an action or close button while its handler's Promise runs.

API Reference

Toast

id?string: Reuses a toast: a toast with this id that's still showing is updated instead of added again.
title?Content: The main message.
description?Content: More detail, under the title.
type?ToastType: What it's about, for styling through data-type, and for how it's announced.
duration?number: How long it shows, in ms, while nothing pauses it. Infinity keeps it until dismissed.
priority?"assertive" | "polite": How screen readers announce it: "polite" waits for a pause, "assertive" interrupts.
action?ToastAction<Content>: A button that does something, like Undo.
cancel?ToastCancel<Content>: A button that dismisses it, like Cancel.
dismissible?boolean: Whether the user can dismiss it: swiping, Escape and Close parts. Timers and dismiss() still close it.
data?unknown: Anything else, for your own rendering, like an avatar.
onDismiss?((details: ToastDismissDetails) => void): Runs when it closes, with why. Calling details.cancel() keeps it.

toast(message, options) and toast(options) return the toast's id. toast.success, .info, .warning, .error and .loading set the type. toast.promise(promise, { loading, success, error }) returns the id too, and toast.update(id, options) returns whether the toast was still there. toast.dismiss(id) closes one, and toast.dismiss() every one.

Actions

labelContent: The button's text.
onAction?((event: Event | undefined, details: ToastActionDetails) => unknown): Runs when it's pressed. A returned Promise marks the action pending, then dismisses the toast once it resolves. A rejection keeps the toast. details.source says how it was pressed, for changes made after an await.
href?string: Makes the action a link.
dismiss?boolean: Whether pressing it dismisses the toast.

labelContent: The button's text.
onCancel?((event: Event | undefined, details: ToastActionDetails) => void): Runs when it's pressed, before the toast closes. details.source says how it was pressed.

ToastRegion

toaster?Toaster<any>: The queue it shows. A second toaster, from createToaster(), gives a second region its own toasts.
side?"bottom" | "top": The edge of the viewport it sits on. Swiping toward it dismisses a toast.
align?"center" | "end" | "start": Where along that edge. "start" and "end" follow the writing direction, and swiping toward them dismisses too.
maxVisible?number: How many toasts show at once. Older ones wait, with their timers stopped, until there's room.
expanded?boolean: Whether the stack is always expanded. Otherwise it expands while the pointer or focus is in it.
shortcut?string | null: The key that moves focus into the region and back, like "F6" or "alt+t". null turns it off.
pendingAnnouncement?string: What screen readers hear once a toast's action or close button has been pending for a second, so a slow action doesn't pass in silence. Set it in the page's language. An empty string says nothing.
debug?boolean: Logs every state change with its reason to the console, in development builds.

ToastAction

action event: Runs when it's pressed, instead of the toast's own action.onAction. A returned Promise marks it pending. details.source says how it was pressed, for changes made after an await.
dismiss?boolean: Whether pressing it dismisses the toast.

ToastClose

action?((event: Event | undefined, details: ToastActionDetails) => unknown): Runs before the toast closes. A returned Promise keeps it open and the button pending until it settles. details.source says how it was pressed, for changes made after an await.

Confirm

titlestring: The question, like "Delete this project?".
description?string: What agreeing does.
confirmLabel?string: The agreeing button's text.
cancelLabel?string: The other button's text.

State

ui-toast-region:

side"top" | "bottom": The edge it sits on.
align"start" | "center" | "end": Where along that edge.
expandedboolean: Whether the stack is expanded.
toastsreadonly ToastItem<unknown>[]: The toasts to render, newest first, including ones animating out.

ui-toast:

typeToastType: What it's about.
indexnumber: Its place in the stack, 0 for the newest.
frontboolean: Whether it's the newest, on top of a collapsed stack. A closing toast keeps it.
expandedboolean: Whether the stack is expanded.
leavingboolean: Whether it's animating out.

ui-toast-action and ui-toast-close:

pendingboolean: Whether a Promise its handler returned is still running.
errorunknown: Why its handler failed, until it's pressed again.

Reasons

timeoutnone: A duration ran out, like a toast's, or a rotating carousel's interval.
close-pressMouseEvent | KeyboardEvent | SubmitEvent: A Close part was pressed, or a form with method="dialog" was submitted.
swipePointerEvent | TouchEvent: A swipe gesture: a finger, mouse or pen dragged it.
escape-keyKeyboardEvent: Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
actionMouseEvent | KeyboardEvent: A Close part's action finished.
imperativenone: A controller or api call, or a property set on a web component.

Accessibility

Toasts are announced through shared live regions, once each, without making the visible region live: politely by default and assertively for errors. While it has toasts, the region is a landmark named Notifications; set aria-label to name it in the page's language. Keep messages short, and use duration: Infinity for one that has to stay available.

Keyboard

F6, or the region's shortcut, moves focus to the newest toast, and pressing it again returns focus to where it came from. Tab moves through the toasts and their buttons, and Tab past the last one goes back too. Escape dismisses the focused toast; focus then moves to the next toast, or back where it came from after the last one. The region stays reachable while a modal dialog is open, and its timers pause while focus is inside.

Tested Behavior

Every line below is an automated test.

Showing

A toast shows its title, description and action in the Notifications region.
Newer toasts come first.
The newest toast is marked as the front one.
Each toast says what it's about through data-type.
The region sits on its side and alignment.
It shows above everything, in the top layer.
A promise toast loads, then shows the result.
A toast with an id that's showing is updated in place.

Closing

A toast closes after its duration.
Infinity keeps it until it's dismissed.
The Dismiss button closes it.
The action runs and closes it.
Escape on a focused toast closes it.
A closing toast stays while it animates out.
A toast that can't be dismissed ignores Escape.

Timers

Hovering the region pauses its timers, and leaving resumes them.
Focus in the region pauses its timers.

Keyboard

F6 moves focus to the newest toast, and again back where it was.
The shortcut is configurable.
The region names its shortcut.
When the focused toast closes, focus goes to the next one, then back where it was.

Stacking

Only maxVisible toasts show; the rest wait for room.
The stack expands while hovered or focused.
Expanded keeps the stack expanded.
Toasts measure their heights and offsets for the stack.
A toast measures its content's height, whatever height it's given.
A toast given its measured height animates to a new one when its content changes.
A toast measures again when a child, its class or its padding changes.
A toast closing from the front stays in front while it animates out.

Swiping

Swiping toward the region's side dismisses.
Swiping toward the aligned edge dismisses too.
A short swipe snaps back.
Swiping away from the side never dismisses.
A toast that can't be dismissed doesn't swipe.

Over a modal dialog

A toast shown from a modal dialog is visible, usable and above it.

Updates after closing

A promise toast dismissed while loading stays closed.
An update after a toast closed never brings it back.

More pausing and keys

The window losing focus pauses timers, and getting it back resumes them.
F6 does nothing while there are no toasts, so the browser keeps it.
A toast on the top edge swipes up, and a swipe down snaps back.

Runs in React, Vue and web components.

Also tested:

Enhancements

Update() says whether the toast was still there.
A toast beyond maxVisible never expires unseen.
There's no empty Notifications landmark.
Focus never falls to the page when a toast focused by the mouse closes.
A pending action shows it and holds the toast open until it settles.

Pausing

A hidden page pauses timers.
Pause reasons hold separately: getting the window back doesn't resume while focus is in the region.

Announcements

The live regions exist before the first toast.
A toast is announced politely, with its title and description.
An error is announced assertively.
Toasts that arrive together are announced together.
The visible region isn't a live region, so nothing is read twice.

The shortcut

F6 works from a text field and types nothing.
A shortcut of null turns it off.
Tab past the last toast goes back where F6 came from.

Over modal dialogs

F6 reaches the toasts from inside a modal dialog, and goes back into it.
Escape on a toast closes the toast, not the dialog beneath.
A dialog opened after a toast doesn't cover it, and pressing it doesn't close the dialog.

Swiping

Dragging across a toast's text with a mouse selects it instead of dismissing.

Runs in React, Vue and web components.

Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:

Announcements while reaching a toast with F6 and leaving it.

Runs in React, Vue and web components.