components / toast

Toast

Data-driven feedback stack for transient notifications with placement, action, and dismissal behavior.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Toast handles transient feedback that should be noticed quickly without interrupting the user’s current flow.
  • Use it for save confirmations, lightweight warnings, and follow-up actions that are helpful but not blocking.

Aliases

notification toast

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Toast when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Toast contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Toast label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Toast behind decorative copy or overloaded surface treatments.
  • Do not stretch Toast into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Toast when the feedback can fade after a short time and does not need to remain inline with nearby content.
  • Use its action affordance for quick follow-up like opening details or undoing a recent change.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Toast for blocking decisions; use Dialog.
  • Do not use Toast as the only place critical information exists if the user may miss it.

Anti-patterns

  • Using Toast as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy toast usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

toast region

stack

Placement-aware stack of transient feedback surfaces.

single toast surface

item

Contains title, description, optional action, and dismiss affordance.

follow-up affordance

action

Optional quick action inside a toast item.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
itemsArray<{ id: string; tone: string; title: string; description?: string; actionLabel?: string; actionHref?: string }>—Data-driven list of toast items to render in the stack.
placement'bottom-right' | 'bottom-left' | 'top-right' | 'top-left''bottom-right'Chooses the stack placement on the viewport.
durationMsnumber5000Auto-dismiss duration for toast items.
dismissiblebooleantrueShows a dismiss affordance when true.
onDismiss(detail: { id?: string }) => void—Callback fired when a toast item is dismissed.
onAction(detail: { id?: string; value?: string }) => void—Callback fired when a toast action is activated.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
dismiss{ id?: string }Fires when the user dismisses the component or one of its items.
action{ id?: string; value?: string }Fires when the component exposes a primary action and the user activates it.

Slots

NameDescription
defaultToast is data-driven and does not expose direct slots in v1.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • brand: General product feedback.
  • success: Positive confirmation.
  • warning: Transient caution message.
  • danger: High-risk or failure feedback.

Sizes

  • default: Toast uses one structural size and varies by placement and message length.

States

  • open: Toast is visible in the stack.
  • dismissed: Toast leaves the stack after timeout or explicit dismissal.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Toast is a transient feedback surface that should still expose readable title and description content.

Keyboard

  • Dismiss buttons and action links remain keyboard reachable while visible.

Screen readers

  • Transient feedback should be understandable even if the user lands on it after it appears.

Caveats

  • Because toasts are transient, critical workflow state should also be reflected elsewhere when needed.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-toast-stack-gap
0.75rem
--dk-toast-stack-inset
1rem
--dk-motion-duration
200ms

item

--dk-toast-item-bg
#f2f5fb
--dk-toast-item-fg
#16181c
--dk-toast-item-border
#95989d
--dk-toast-item-shadow
0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)
--dk-toast-item-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-toast-item-padding
1rem
--dk-toast-item-max-width
320px

title

--dk-toast-title-size
0.9375rem
--dk-toast-title-weight
650

description

--dk-toast-description-size
0.8125rem

action

--dk-toast-action-bg
#d7e9ff
--dk-toast-action-fg
#000f4d
--dk-toast-action-radius
999px
--dk-toast-action-inline-padding
0.75rem
--dk-toast-action-block-size
36px
--dk-toast-action-size
0.8125rem

dismiss

--dk-toast-dismiss-size
44px

Implementation notes

  • Toast remains data-driven in v1; there is no global imperative service in the component contract.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
expanded

Starter

1 example

starter

Starter: save confirmation

A basic transient confirmation for a successful save.

Copy snippet

<Toast items={[{ id: 'saved', tone: 'brand', title: 'Saved', description: 'Workspace updated.' }]} />

Common patterns

1 example

common

Common: undo-capable feedback

Use an action when the user may want to quickly reverse or inspect the result.

Copy snippet

<Toast items={[{ id: 'archive', tone: 'warning', title: 'Archived', description: 'Project moved to archive.', actionLabel: 'Undo' }]} onAction={(detail) => console.log(detail)} />

Edge cases

1 example

edge

Edge: long-running stack

Longer visibility works for inspection-heavy flows but should still feel lightweight.

Copy snippet

<Toast placement="top-right" durationMs={20000} dismissible={false} items={[{ id: 'sync', tone: 'success', title: 'Sync complete', description: 'All records are in sync.' }]} />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

toast-bottom-right

pass

placement=bottom-right

  • Contrast: 98.5 Lc
  • Target: 44px
  • Surface: 320x120
  • Motion: 200ms

toast-top-left

pass

placement=top-left

  • Contrast: 98.5 Lc
  • Target: 44px
  • Surface: 320x120
  • Motion: 200ms