Feedback

ToastRegion

Provider region that hosts polite and assertive toast stacks and exposes an imperative show/dismiss API via context.

import { ToastRegion } from '@lostgradient/cinder/toast-region';
feedbacktoast
01

Overview

ToastRegion provides live toast notifications and a useToast() controller for descendants.

Usage

svelte 
<script lang="ts">
  import ToastRegion from '@lostgradient/cinder/toast-region';
</script>

<ToastRegion />
Live preview
02

When to use

Use when
  • Surfacing transient, non-blocking confirmations or errors that auto-dismiss after a short duration.
  • Announcing the outcome of a background action that the user does not need to acknowledge.
Avoid when
  • Communicating a persistent page-level message — use banner so it stays until dismissed.
  • Reporting an urgent error that must remain on screen — use alert.
03

Examples

Action button

Default action dismisses after firing; keepOpen: true keeps the toast visible after the action runs.

Basic toast region

Click the trigger to dispatch a transient toast into the live region.

Dismissible sticky toast

duration: 0 keeps the toast until the user dismisses it.

Keyboard dismiss

Focus a toast control and press Escape to dismiss the active notification.

Modal-scoped region

Nest <ToastRegion> inside a Modal to scope toasts to the modal content. When the modal body unmounts on close, the region tears down with it and pending timers are cleared.

Pause on hover

Pointer hover and keyboard focus pause auto-dismiss for the whole stack.

Positions

Anchor the toast region to any viewport corner or horizontal center.

Programmatic dismiss

show() returns the toast id. Capture it to dismiss a specific toast, or call dismissAll() to clear both stacks.

Promise

Show a sticky loading toast that resolves into success or danger output.

Stacking

Rapid notifications stack with bounded overflow and visual depth.

Swipe to dismiss

Dismiss a toast by dragging it horizontally past the threshold.

All four variants

info, success, and warning route to the polite (status) region; danger routes to the assertive (alert) region.

04

Props

Props for toast-region
Name Type Default Required Bindable Description
maxStack number 5 Maximum simultaneous toasts in each region. Default 5.
defaultDuration number 5000 Default auto-dismiss duration in ms. Default 5000. Set to 0 for sticky.
position 'top-left''top-center''top-right''bottom-left''bottom-center''bottom-right' 'bottom-right' Viewport anchor for both live-region channels. Default bottom-right.
children snippet Optional children. When provided, the region wraps them so descendants can call useToast() and read the region's context. Most apps mount <ToastRegion> as a self-closing tag at the root of their layout and leave this empty — but some patterns (modal-scoped regions, tests) benefit from explicit child composition.