Toast

A notification system that displays brief messages to users with automatic dismissal options.

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

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

  return (
    <div>
      <button
        type="button"
        class="toast-trigger"
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Open Toast
      </button>
      <Toast.Root bind:open={isOpen} class="toast-root">
        <Toast.Title>Toast Accessible Title</Toast.Title>
        <Toast.Description>Toast Accessible Description</Toast.Description>
        <Toast.Close class="toast-close">Close Me</Toast.Close>
      </Toast.Root>
    </div>
  );
});

Features

Anatomy

Examples

Basic Usage

Default Toast

The Toast component provides a way to show temporary notifications to users. It automatically dismisses after a set duration and can be manually closed.

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

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

  return (
    <div>
      <button
        type="button"
        class="toast-trigger"
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Open Toast
      </button>
      <Toast.Root bind:open={isOpen} class="toast-root">
        <Toast.Title>Toast Accessible Title</Toast.Title>
        <Toast.Description>Toast Accessible Description</Toast.Description>
        <Toast.Close class="toast-close">Close Me</Toast.Close>
      </Toast.Root>
    </div>
  );
});

In this example, we're using the basic Toast structure with:

• <Toast.Root> as the container component
• <Toast.Title> for the accessible title
• <Toast.Description> for the detailed message
• <Toast.Close> for the dismissal button The toast is triggered by a button click that sets the isOpen signal to true.

Custom Duration

You can customize how long the toast appears before automatically dismissing.

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

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

  return (
    <div>
      <button
        type="button"
        class="toast-trigger"
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Open Toast
      </button>
      <Toast.Root bind:open={isOpen} duration={2000}>
        <Toast.Title>Custom Duration Toast</Toast.Title>
        <Toast.Description>
          This toast will close automatically after 2 seconds
        </Toast.Description>
        <Toast.Close>Close Me</Toast.Close>
      </Toast.Root>
    </div>
  );
});

This example sets a custom duration of 2 seconds using the duration prop on <Toast.Root>. The default duration is 5 seconds.

Signal Binding

Toast state can be bound to a signal for external state management.

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

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

  return (
    <div>
      <button
        type="button"
        class="toast-trigger"
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Open Toast
      </button>
      <p>Is open: {isOpen.value.toString()}</p>
      <Toast.Root bind:open={isOpen}>
        <Toast.Title>Signal Binding Toast</Toast.Title>
        <Toast.Description>This toast demonstrates signal binding</Toast.Description>
        <Toast.Close>Close Me</Toast.Close>
      </Toast.Root>
    </div>
  );
});

The bind:open prop creates a two-way binding with the provided signal, allowing you to track the toast's open state from outside the component.

Change Callback

You can respond to toast state changes with the onChange$ callback.

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

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

  const handleChange$ = $((open: boolean) => {
    changeCount.value++;
  });

  return (
    <div>
      <button
        type="button"
        class="toast-trigger"
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Open Toast
      </button>
      <p>onChange called: {changeCount.value}</p>
      <Toast.Root bind:open={isOpen} onChange$={handleChange$}>
        <Toast.Title>onChange Toast</Toast.Title>
        <Toast.Description>This toast demonstrates onChange$ callback</Toast.Description>
        <Toast.Close>Close Me</Toast.Close>
      </Toast.Root>
    </div>
  );
});

The onChange$ callback is triggered whenever the toast opens or closes, allowing you to perform side effects or track usage.

Component State

Using Component State

The Toast component provides several ways to control its state through props and callbacks.

Controlling Open State

As shown in the Basic Usage example above, you can control the toast's visibility using the bind:open prop with a signal:

const isOpen = useSignal(false);
<Toast.Root bind:open={isOpen}>
  <Toast.Title>Toast Title</Toast.Title>
  <Toast.Description>Toast Description</Toast.Description>
  <Toast.Close>Close</Toast.Close>
</Toast.Root>

This creates a two-way binding between your application state and the toast's open state. When the toast opens or closes, the bound signal will update accordingly.

Auto-Dismissal Duration

As shown in the Custom Duration example above, you can control how long the toast appears before automatically dismissing:

<Toast.Root bind:open={isOpen} duration={2000}>
  <!-- Toast content -->
</Toast.Root>

The duration prop accepts a value in milliseconds. The default duration is 5000ms (5 seconds). Setting duration to 0 will disable auto-dismissal.

State Interactions

Responding to State Changes

As shown in the Change Callback example above, you can use the onChange$ prop to respond to toast state changes:

const handleChange$ = $((open: boolean) => {
  // Perform actions when toast opens or closes
  console.log(`Toast is now ${open ? 'open' : 'closed'}`);
});
<Toast.Root bind:open={isOpen} onChange$={handleChange$}>
  <!-- Toast content -->
</Toast.Root>

The onChange$ callback receives the current open state as a boolean parameter. This is useful for tracking usage, logging, or triggering additional actions when the toast opens or closes.

Pause on Hover

The Toast component automatically pauses its auto-dismissal timer when the user hovers over it. This behavior is built-in and requires no additional configuration. When the user moves their cursor away from the toast, the timer resumes with the remaining time. This feature ensures that users have enough time to read and interact with the toast content, especially for longer messages or when the toast contains interactive elements like buttons or links.

Configuration

Core Configuration

Duration Settings

The Toast component automatically dismisses after a set duration. You can customize this duration using the duration prop on <Toast.Root>.

<Toast.Root duration={3000}>
  {/* Toast content */}
</Toast.Root>

The duration prop accepts a value in milliseconds. The default duration is 5000ms (5 seconds). Setting duration to 0 will disable auto-dismissal, requiring the user to manually close the toast. As shown in the Custom Duration example above, you can set a custom duration of 2000ms (2 seconds) to make the toast dismiss more quickly.

Advanced Configuration

Pause on Hover Behavior

The Toast component automatically pauses its auto-dismissal timer when the user hovers over it. This behavior is built-in and requires no additional configuration. When the user moves their cursor away from the toast, the timer resumes with the remaining time. This feature ensures that users have enough time to read and interact with the toast content, especially for longer messages or when the toast contains interactive elements like buttons or links.

State Change Callback

For advanced use cases, you can track toast state changes using the onChange$ callback:

const handleChange$ = $((open: boolean) => {
  // Perform actions when toast opens or closes
  console.log(`Toast is now ${open ? 'open' : 'closed'}`);
});
<Toast.Root onChange$={handleChange$}>
  {/* Toast content */}
</Toast.Root>

As shown in the Change Callback example above, the onChange$ callback receives the current open state as a boolean parameter. This is useful for tracking usage, logging, or triggering additional actions when the toast opens or closes.

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

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

  return (
    <div>
      <button
        type="button"
        class="toast-trigger"
        onClick$={() => {
          isOpen.value = true;
        }}
      >
        Open Toast
      </button>
      <Toast.Root bind:open={isOpen} duration={2000}>
        <Toast.Title>Custom Duration Toast</Toast.Title>
        <Toast.Description>
          This toast will close automatically after 2 seconds
        </Toast.Description>
        <Toast.Close>Close Me</Toast.Close>
      </Toast.Root>
    </div>
  );
});