Toast

<button
  class="btn" data-variant="outline"
  hx-trigger="click"
  hx-select="unset"
  hx-get="/fragments/toast/success"
  hx-target="#toaster"
  hx-swap="beforeend"
  hx-push-url="false"
>Toast from backend (with HTMX)</button>

<button
  class="btn" data-variant="outline"
  onclick="document.getElementById('toaster').toast({
    category: 'success',
    title: 'Success',
    description: 'A success toast called from the front-end.',
    cancel: {
      label: 'Dismiss'
    }
  })"
>Toast from front-end</button>

Usage

Template macros available

This component ships toaster() and toast() macros for Jinja and Nunjucks.

Include CSS

Import Tailwind and one full Basecoat style bundle.

@import "tailwindcss";
@import "basecoat-css/vega.css";

Or import only the base CSS, Toast component CSS, and one style pack.

@import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/toast.css";
@import "basecoat-css/styles/vega.css";

Using CDN or bundler imports? See the Installation page.

Include JavaScript

Copy or serve the full Basecoat JavaScript bundle.

<script src="/assets/js/all.min.js" defer></script>

Or copy or serve the Basecoat runtime and Toast script.

<script src="/assets/js/basecoat.min.js" defer></script>
<script src="/assets/js/toast.min.js" defer></script>

Using CDN or bundler imports? See the Installation page.

Add the toaster HTML

Add one toaster near the end of your page body:

<div id="toaster" class="toaster"></div>

Set data-align="start", data-align="center", or data-align="end" on the toaster to change placement.

Add your toasts

Append server-rendered toast markup to the toaster, or create one from JavaScript with toaster.toast(config).

<div id="toaster" class="toaster">
  <div class="toast" role="status" aria-atomic="true" aria-hidden="false" data-category="success">
    <div class="toast-content"><svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10" /><path d="m9 12 2 2 4-4" /></svg>
      <section>
        <h2>Success</h2>
        <p>A success toast called from the front-end.</p>
      </section>
      <footer>
        <button type="button" class="btn" data-toast-action>Dismiss</button>
      </footer>
    </div>
  </div>
</div>

<button
  class="btn" data-variant="outline"
  onclick="document.getElementById('toaster').toast({
    category: 'success',
    title: 'Success',
    description: 'A success toast called from the front-end.',
    cancel: {
      label: 'Dismiss'
    }
  })">Toast from front-end</button>

HTML structure

<div id=“toaster” class=“toaster”>

Toast container. Optional data-align values are start, center, and end.

<div class=“toast”>

Toast item. Use data-category=“success|info|warning|error” for category styling and data-duration to override the timeout in milliseconds. Use data-duration=“-1” to keep it open.

<div class=“toast-content”>

Content wrapper.

<svg aria-hidden=“true”> Optional

Icon.

<section>

Message region.

<h2>: Title.
<p> Optional: Description.

<footer> Optional

Action buttons or links. Clicking a footer button or link closes the toast.

JavaScript API

API	Type	Description
`toaster.toast(config)`	Method	Creates a toast from a config object and returns the inserted `.toast` element. See “Config object” below.
`toaster.closeAll()`	Method	Closes every toast inside the toaster.
`toast.close()`	Method	Closes one initialized toast element.

Text is escaped by default

title, description, and action labels are inserted as plain text. With html: true they are inserted as HTML, so never pass untrusted user input with it. onclick is JavaScript code and must never contain user input. icon is always inserted as raw HTML (it is meant for SVG markup).

duration Optional: Timeout in milliseconds. Defaults to 3000, or 5000 for error toasts. Use -1 to keep it open.
category Optional: Category of the toast, either success, info, warning, or error.
title: The title of the toast.
description Optional: The description of the toast.
action Optional: Primary action. Supports label with either href or onclick.
cancel Optional: Secondary action. Supports label and optional onclick.
icon Optional: Custom icon markup, usually an SVG. Inserted as raw HTML. Defaults to the category icon.
html Optional: Set to true to insert title, description, and action labels as HTML instead of plain text. Defaults to false. Only use it with trusted content.

The Jinja and Nunjucks toast() macros render on your server, so your template engine’s autoescaping applies to title, description, and labels there when it is enabled. Nunjucks enables it by default. With Jinja, make sure your environment’s autoescape setting covers the Basecoat template files (for example .html.jinja). icon is output with safe, and onclick is output as an attribute, so neither should contain user input.