Toast

A toast is a sm notification surface, modeled on the push notifications native to mobile and desktop operating systems. It's positioned and stacked with flexbox, so alignment follows the same margin and flexbox utility classes as the rest of Chassis.

Overview

<Toast> renders a single notification. Nothing shows until you ask for it.

• Toasts are opt-in — nothing renders until visible or defaultVisible is set, or addToast() pushes one into a Toaster's queue.
• defaultVisible shows a toast that then hides itself: by its close button, autohide, or close. visible makes it controlled: those become requests, reported to onVisibleChange(false), and the toast hides when you set visible to false. A state setter fits as it is: visible={open} onVisibleChange={setOpen}. onClose fires after the toast has hidden.
• A toast automatically hides after delay milliseconds unless autohide is set to false. The countdown pauses while the pointer is over the toast or focus is within it, and only resumes once both leave.
• Use role="status" (the default) for routine confirmations and informational updates. Reserve role="alert" for errors and messages requiring immediate attention. Both roles carry implicit live-region semantics, so no separate aria-live prop is needed.
• The icon/title/time/message/footer/closeButton props are shorthand for the manual ToastHeader/ToastBody/ToastFooter composition — reach for manual composition only when a toast needs more than one header/body/footer block. See Shorthand props.
• To dismiss a toast from custom markup — a "Close" button in the footer, a custom icon in the header — either pass a function to footer to receive close directly (see Action footer), or call useToast() from any child component and wire its close to an element's onClick.

Examples

Basic layout

A toast typically pairs a header and body — the header uses display: flex, aligning icon, title, and timestamp content with the margin and flexbox utility classes.

A toast needs very little required markup: at minimum, a single element containing its content. A dismiss button is recommended but not enforced.

import { Toast, ToastBody, ToastHeader, Icon } from '@chassis-ui/react'

export const Example = () => {
  const icon = <Icon name="info-circle-solid" />
  return (
    <Toast defaultVisible autohide={false}>
      <ToastHeader icon={icon} time="7 min ago" closeButton>
        Chassis
      </ToastHeader>
      <ToastBody>Hello, world! This is a toast message.</ToastBody>
    </Toast>
  )
}

For dynamic notifications, call addToast() from anywhere — an event handler, an async callback — to push a toast into a Toaster's queue. Toaster renders whatever's currently queued; nothing else needs to know about it.

import { Button, ToastBody, ToastHeader, Toaster, addToast, Icon } from '@chassis-ui/react'

export const Example = () => {
  const icon = <Icon name="info-circle-solid" />
  const handleClick = () => {
    addToast(
      <>
        <ToastHeader icon={icon} time="7 min ago" closeButton>
          Chassis
        </ToastHeader>
        <ToastBody>Hello, world! This is a toast message.</ToastBody>
      </>
    )
  }
  return (
    <>
      <Button onClick={handleClick}>Send a toast</Button>
      <Toaster placement="bottom-end" />
    </>
  )
}

Shorthand props

For the common case — an icon, a heading, a timestamp, one block of message text — icon/title/time/message render the same markup as composing ToastHeader/ToastBody by hand, without the wiring. icon accepts an icon name (rendered via ToastIcon) or any other node for a fully custom icon, such as a logo or avatar. Add footer for a single row of trailing content (shorthand for ToastFooter), and closeButton/closeLabel for the dismiss control and its accessible name. closeButton follows whatever header content is set: it lands in the header when icon/title/time is present, otherwise alongside message in the body — so a title-less toast never gets a header that exists only to hold a close button. When both title and message are set, the toast's aria-labelledby/aria-describedby are wired to them automatically. icon is hidden from assistive technology by default, since it duplicates title visually.

import { Toast, Icon } from '@chassis-ui/react'

export const Example = () => {
  const icon = <Icon name="info-circle-solid" />
  return (
    <Toast
      animation={false}
      autohide={false}
      defaultVisible
      icon={icon}
      title="Chassis"
      time="7 min ago"
      message="Hello, world! This is a toast message."
      closeButton
    />
  )
}

icon/title/time/message/footer are additive with children — for multi-block content (more than one header, body, or footer region), compose ToastHeader/ToastBody/ToastFooter manually instead, as in the sections below. ToastHeader itself takes the same shorthand shape — icon/time as props, the heading as children — so manual composition never requires hand-writing the <strong>/<span> markup.

Action footer

Add a ToastFooter below the body to hold acknowledgement or follow-up actions, or pass footer for the same result without composing ToastFooter by hand — it renders .toast-footer, separated from the body by a border that matches the header rule.

A "Close" action is just a normal Button. Passing a function to footer provides close as its argument, so a button can wire it straight to onClick without a child component calling useToast() itself — useful when the footer's only custom need is the close handler. For anything with its own local state or logic, calling useToast() from a child component works the same way, and is the only option outside footer (a custom icon in the header, for example).

import { Button, Toast, ToastBody } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Toast
      autohide={false}
      defaultVisible
      footer={(close) => (
        <>
          <Button type="button" color="primary" size="sm">
            Take action
          </Button>
          <Button type="button" size="sm" onClick={close}>
            Close
          </Button>
        </>
      )}
    >
      <ToastBody>Hello, world! This is a toast message.</ToastBody>
    </Toast>
  )
}

Translucent

Add translucent to blend the toast in with what's below it.

import { Toast, ToastBody, ToastHeader, Icon } from '@chassis-ui/react'

export const Example = () => {
  const icon = <Icon name="info-circle-solid" />
  return (
    <Toast translucent autohide={false} defaultVisible>
      <ToastHeader icon={icon} time="7 min ago" closeButton>
        Chassis
      </ToastHeader>
      <ToastBody>Hello, world! This is a toast message.</ToastBody>
    </Toast>
  )
}

Stacking

Wrapping toasts in a Toaster stacks them, adding vertical spacing between each automatically.

import { Toast, ToastBody, ToastHeader, Toaster, Icon } from '@chassis-ui/react'

export const Example = () => {
  const icon = <Icon name="info-circle-solid" />
  return (
    <Toaster>
      <Toast autohide={false} defaultVisible>
        <ToastHeader icon={icon} time="7 min ago" closeButton>
          Chassis
        </ToastHeader>
        <ToastBody>Hello, world! This is a toast message.</ToastBody>
      </Toast>
      <Toast autohide={false} defaultVisible>
        <ToastHeader icon={icon} time="7 min ago" closeButton>
          Chassis
        </ToastHeader>
        <ToastBody>Hello, world! This is a toast message.</ToastBody>
      </Toast>
    </Toaster>
  )
}

Simplified layout

Toast sub-components can be omitted or adjusted with props to simplify the layout. This example removes the default <ToastHeader> and adds closeButton directly to <ToastBody>, so no manual markup is needed to lay out the dismiss control.

import { Toast } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Toast autohide={false} defaultVisible>
      Hello, world! This is a toast message.
    </Toast>
  )
}

Color schemes

Apply color and add solid for a full-color background with inverted text — the example below sets color="primary" and solid on the <Toast>.

import { Toast, ToastBody } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Toast autohide={false} defaultVisible color="primary" solid>
      <ToastBody closeButton>Hello, world! This is a toast message.</ToastBody>
    </Toast>
  )
}

API

Toast

ToastHeader

ToastIcon

ToastBody

ToastFooter

Toaster