Toast

Displays brief, temporary notifications that automatically disappear after a set time.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Toast } from "@kunai-consulting/qwik";
import styles from "./toast.css?inline";

export default component$(() => {
  useStyles$(styles);
  const isOpen = useSignal(false);

  return (
    <>
      <button
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Show Toast
      </button>

      <Toast.Root
        id="success-toast"
        position="top-center"
        duration={3000}
        bind:open={isOpen}
        class="toast-root"
      >
        <Toast.Content>
          <div class="toast-content">
            <span>✅</span>
            <p>Operation completed successfully!</p>
          </div>
        </Toast.Content>
      </Toast.Root>
    </>
  );
});

Features

Anatomy

Examples

Basic Usage

The toast component can be implemented with minimal configuration using the position and duration props. The position prop determines where the toast appears on screen, while duration sets how long it remains visible.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Toast } from "@kunai-consulting/qwik";
import styles from "./toast.css?inline";

export default component$(() => {
  useStyles$(styles);
  const isOpen = useSignal(false);

  return (
    <>
      <button
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Show Toast
      </button>

      <Toast.Root
        id="success-toast"
        position="top-center"
        duration={3000}
        bind:open={isOpen}
        class="toast-root"
      >
        <Toast.Content>
          <div class="toast-content">
            <span>✅</span>
            <p>Operation completed successfully!</p>
          </div>
        </Toast.Content>
      </Toast.Root>
    </>
  );
});

In this example, we use:

• Toast.Root with position="bottom-right" and duration={5000} for positioning and timing
• Toast.Content to display the message
• bind:open prop for controlling visibility state

Visual Features

Toast Positioning

Toasts can be positioned in six different locations on the screen using the position prop:

• top-left
• top-right
• top-center
• bottom-left
• bottom-right
• bottom-center

Each position value affects where the toast appears relative to the viewport edges.

Advanced Usage

Multiple Toasts

Multiple toasts can be displayed simultaneously, each with its own position and timing. Each toast operates independently and can be controlled separately.

Component State

Using Component State

The Toast component's state can be controlled in two primary ways:

1. Uncontrolled State Use the open prop to set the initial visibility state of the toast:

<Toast.Root open={false}>
  <Toast.Content>Message</Toast.Content>
</Toast.Root>

2. Controlled State For reactive control, use the bind:open prop with a boolean signal: As shown in the hero example, you can control the toast's visibility state and respond to changes: The example demonstrates:

• Using bind:open for two-way binding
• Setting duration for automatic closing
• Positioning with the position prop Key state-related props:
• open: Sets initial visibility state
• bind:open: Enables controlled state management
• duration: Controls auto-dismiss timing (defaults to 5000ms)
• position: Determines toast placement (defaults to "bottom-right")

State Interactions

The toast component provides several ways to interact with its state:

1. Automatic Dismissal By default, toasts automatically dismiss after the specified duration. As shown in the hero example, setting duration={5000} will close the toast after 5 seconds.
2. Manual Control You can manually control the toast's visibility:

<button onClick$={() => (isOpen.value = true)}>Show</button>
<button onClick$={() => (isOpen.value = false)}>Hide</button>
<Toast.Root bind:open={isOpen}>
  <Toast.Content>Controlled toast</Toast.Content>
</Toast.Root>

3. Multiple Toast Management As demonstrated in the hero example, multiple toasts can be managed independently:

• Each toast maintains its own state
• Toasts can have different positions and durations
• Toasts can be shown and hidden independently The toast's state is reflected in its data attributes:
• data-state: Shows current visibility ("visible" | "hidden")
• data-position: Indicates current position on screen These attributes can be used for styling or testing purposes.

Based on the provided implementation and examples, I'll document the Toast configuration options.

Core Configuration

Positioning

The Toast component supports six positioning options through the position prop on Toast.Root:

• top-left
• top-right
• top-center
• bottom-left
• bottom-right (default)
• bottom-center

As shown in the hero example above, the position can be set using the position prop:

type ToastPosition =
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "top-center"
  | "bottom-center";

Duration

The duration prop controls how long the toast remains visible before automatically closing. The default duration is 5000 milliseconds (5 seconds).

• Set to 0 to disable auto-closing
• Values are in milliseconds
• Minimum recommended duration: 2000ms
• Maximum recommended duration: 10000ms

State Management

The Toast component supports both controlled and uncontrolled state management:

1. Uncontrolled: Use the open prop for initial state
2. Controlled: Use the bind:open prop with a signal

Note: When using bind:open, the duration timer will automatically clean up if the component unmounts.

Advanced Configuration

Multiple Toasts

The Toast system supports multiple simultaneous toasts, each requiring a unique id. When not provided, an ID is automatically generated using crypto.randomUUID(). As shown in the hero example above, each toast operates independently with its own:

• Position
• Duration
• State management
• Animation timing

Technical Constraints

1. Positioning: Toast positions are fixed relative to the viewport
2. Stacking: Multiple toasts in the same position stack in order of appearance
3. Animation: State changes trigger CSS transitions via the data-state attribute
4. Cleanup: Timeout handlers are automatically cleaned up on:
   • Component unmount
   • Duration changes
   • Manual close events