Toast

The Toast component provides a simple imperative API to display notification messages. Use Toast.show() to create toasts programmatically.

Toast.show()

The primary method for displaying toasts. It accepts content and toastOptions, and returns a controller for managing the toast.

Toast.show(content, toastOptions);
// or
Toast.show(toastOptions);

Basic Usage

The simplest way to show a toast is to pass a string or ReactNode as content and an optional options object with a title.

import { Button, Toast } from 'react-dialogues';

<Button
  onClick={() => {
    Toast.show('Hello! This is a basic toast notification.', {
      title: 'Basic Toast',
    });
  }}
>
  Show Basic Toast
</Button>;

Notification Types

Shorthand methods for showing toasts with predefined notification styles. Each method automatically applies the corresponding icon and styling. Under the hood, they just call Toast.show() with the type property set.

Use these methods for quick feedback messages with appropriate visual styling.

Available methods:

Toast.info()
Toast.success()
Toast.warning()
Toast.error()

import { Button, Footer, Toast } from 'react-dialogues';

<Footer>
  <Button
    onClick={() => {
      Toast.info({ title: 'Info', content: '…' });
    }}
  >
    Info
  </Button>
  <Button
    color="success"
    onClick={() => {
      Toast.success({ title: 'Success', content: '…' });
    }}
  >
    Success
  </Button>
  <Button
    color="warning"
    onClick={() => {
      Toast.warning({ title: 'Warning', content: '…' });
    }}
  >
    Warning
  </Button>
  <Button
    color="error"
    onClick={() => {
      Toast.error({ title: 'Error', content: '…' });
    }}
  >
    Error
  </Button>
</Footer>

Placement

Control where toasts appear on the screen with the placement property.

Available placements:

'topLeft'
'top'
'topRight'
'bottomLeft'
'bottom'
'bottomRight'

import { Button, Toast } from 'react-dialogues';

type ToastPlacement =
  | 'bottom'
  | 'bottomLeft'
  | 'bottomRight'
  | 'top'
  | 'topLeft'
  | 'topRight';

const placements: ToastPlacement[] = [
  'topLeft',
  'top',
  'topRight',
  'bottomLeft',
  'bottom',
  'bottomRight',
];

<div
  style={{
    display: 'grid',
    gridTemplateColumns: 'repeat(3, 1fr)',
    gap: '8px',
  }}
>
  {placements.map((placement) => (
    <Button
      key={placement}
      onClick={() => {
        Toast.show({
          title: placement,
          content: `This toast appears at ${placement}.`,
          placement,
        });
      }}
    >
      {placement}
    </Button>
  ))}
</div>;

Duration

Control how long a toast stays visible with the duration property.

Options:

Number in milliseconds (default: 5000)
0 for persistent toasts that stay until manually closed

import { Button, Footer, Toast } from 'react-dialogues';

<Footer align="left">
  <Button
    onClick={() => {
      Toast.show({
        title: 'Quick Toast',
        content: 'This disappears in 2 seconds.',
        duration: 2000,
      });
    }}
  >
    2 seconds
  </Button>
  <Button
    onClick={() => {
      Toast.show({
        title: 'Default Toast',
        content: 'This disappears in 5 seconds (default).',
      });
    }}
  >
    5 seconds (default)
  </Button>
  <Button
    onClick={() => {
      Toast.show({
        title: 'Long Toast',
        content: 'This disappears in 10 seconds.',
        duration: 10000,
      });
    }}
  >
    10 seconds
  </Button>
  <Button
    onClick={() => {
      Toast.show({
        title: 'Persistent Toast',
        content: 'This toast stays until manually closed.',
        duration: 0,
      });
    }}
  >
    Persistent
  </Button>
</Footer>;

Progress Bar

Toasts show a progress bar by default indicating time remaining. Control this with the showProgress property.

Options:

showProgress - Boolean, shows countdown progress bar when true (default)

import { Button, Footer, Toast } from 'react-dialogues';

<Footer align="left">
  <Button
    onClick={() => {
      Toast.show({
        title: 'With Progress',
        content: 'Progress bar is visible (default).',
        showProgress: true,
      });
    }}
  >
    With Progress
  </Button>
  <Button
    onClick={() => {
      Toast.show({
        title: 'No Progress',
        content: 'Progress bar is hidden.',
        showProgress: false,
      });
    }}
  >
    Without Progress
  </Button>
</Footer>;

Pause on Hover

By default, the toast timer pauses when you hover over it. Control this with the pauseOnHover property.

Options:

pauseOnHover - Boolean, pauses countdown on hover when true (default)

import { Button, Footer, Toast } from 'react-dialogues';

<Footer align="left">
  <Button
    onClick={() => {
      Toast.show({
        title: 'Pause on Hover',
        content: 'Hover over this toast to pause …',
        pauseOnHover: true,
      });
    }}
  >
    Pause on Hover
  </Button>
  <Button
    onClick={() => {
      Toast.show({
        title: 'No Pause',
        content: 'This toast ignores hover …',
        pauseOnHover: false,
      });
    }}
  >
    No Pause on Hover
  </Button>
</Footer>;

Toast.showCustom()

Displays a toast with a completely custom component. Use this when you need full control over the toast's content and behavior. Under the hood, it's just a shortcut for Toast.show({ component: YourComponent }).

Key points:

Your component receives all standard toast props
Use useRdController() to access the controller
Call controller.destroy() to close the toast programmatically

import { Button, Toast, useRdController } from 'react-dialogues';
import { useState } from 'react';

function CustomProgressToast() {
  const controller = useRdController();
  const [progress, setProgress] = useState(0);

  const handleStart = () => {
    const interval = setInterval(() => {
      setProgress((prev) => {
        if (prev >= 100) {
          clearInterval(interval);
          controller.destroy('complete');
          return 100;
        }
        return prev + 10;
      });
    }, 300);
  };

  return (
    <Toast title="Custom" showProgress={false} duration={0}>
      <div>
        <p>Progress: {progress}%</p>
        <div
          style={{
            width: '100%',
            height: '8px',
            backgroundColor: '#e5e7eb',
            borderRadius: '4px',
          }}
        >
          <div
            style={{
              width: `${progress}%`,
              height: '100%',
              backgroundColor: '#3b82f6',
              borderRadius: '4px',
              transition: 'width 0.2s',
            }}
          />
        </div>
        <Button onClick={handleStart}>Start</Button>
      </div>
    </Toast>
  );
}

<Button
  onClick={() => {
    Toast.showCustom(CustomProgressToast);
  }}
>
  Show Custom Toast
</Button>;

Toast.destroyAll()

Closes all currently visible toasts at once.

Parameters:

action - Optional action name (default: 'destroyAll')
result - Optional result value

import { Button, Footer, Toast } from 'react-dialogues';

<Footer align="left">
  <Button
    onClick={() => {
      Toast.show({ title: 'Toast 1', content: 'First' });
      Toast.show({ title: 'Toast 2', content: 'Second' });
      Toast.show({ title: 'Toast 3', content: 'Third' });
    }}
  >
    Show 3 Toasts
  </Button>
  <Button
    color="error"
    onClick={() => {
      Toast.destroyAll();
    }}
  >
    Destroy All
  </Button>
</Footer>;

Toast.defaults

A static object containing the default values for toast options. You can modify these to change the defaults for all toasts in your application.

import { Toast } from 'react-dialogues';

// Modify defaults globally
Toast.defaults.placement = 'topRight';
Toast.defaults.duration = 3000;
Toast.defaults.showProgress = false;

// All future toasts will use these new defaults
Toast.show({ title: 'Now Top Right', content: '…' });

API Reference

Toast options

Property	Type	Default	Description
`duration`	`number`	`5000`	Auto-dismiss time in ms (0 = persistent)
`keepOnFocusLoss`	`boolean`	`true`	Keep toast visible when tab loses focus
`pauseOnHover`	`boolean`	`true`	Pause countdown when hovering
`placement`	`ToastPlacement`	`'bottomRight'`	Position on screen
`showProgress`	`boolean`	`true`	Show countdown progress bar

Inherited from DialogProps

These properties are inherited from the base Dialog component:

Property	Type	Default	Description
`actionMode`	`'okClose' \| 'simplified' \| 'full'`	`'simplified'`	Controls how button actions resolve the promise
`body`	`ReactNode`	-	Direct body content (bypasses content wrapper)
`buttons`	`DialogButton[]`	-	Array of buttons
`className`	`string`	-	CSS class for toast
`classNames`	`Partial<Record<ToastSlots, string>>`	-	CSS classes for internal slots
`close`	`ReactNode`	-	Custom close button element
`component`	`ComponentType`	-	Custom component to render instead of Toast
`content`	`ReactNode`	-	Toast body content
`empty`	`boolean`	`false`	Render only content without header/footer
`firstChild`	`ReactNode`	-	Content inserted before all other elements
`footer`	`ReactNode`	-	Custom footer element (overrides buttons)
`header`	`ReactNode`	-	Custom header element (overrides title)
`icon`	`ReactNode`	-	Custom icon element
`lastChild`	`ReactNode`	-	Content inserted after all other elements
`onClose`	`(result) => void`	-	Called when toast closes
`title`	`ReactNode`	-	Toast header title
`type`	`'success' \| 'info' \| 'warning' \| 'error'`	-	Notification type styling

Also, you can pass any other properties of HTMLDivElement that are applied to the toast's root element.

ToastSlots

CSS class targets for styling internal toast elements via the classNames prop. Extends DialogSlots with the progress bar slot.

type ToastSlots =
  | 'body'
  | 'footer'
  | 'header'
  | 'icon'
  | 'iconWrap'
  | 'progress';

// Usage
Toast.show({
  title: 'Styled Toast',
  content: 'Custom styling example',
  classNames: {
    header: 'custom-header',
    body: 'custom-body',
    progress: 'custom-progress',
  },
});

Return Value

Toast.show() returns an RdController that implements Promise<[action, result]>:

const controller = Toast.show({ title: 'Example', content: 'Hello' });

// Promise methods
const [action, result] = await controller;

// Controller methods
controller.update({ title: 'Updated Title' }); // Update toast props
controller.destroy('cancel'); // Close toast programmatically

Toast.show()​

Basic Usage​

Notification Types​

Placement​

Duration​

Progress Bar​

Pause on Hover​

Toast.showCustom()​

Toast.destroyAll()​

Toast.defaults​

API Reference​

Toast options​

Inherited from DialogProps​

ToastSlots​

Return Value​

Toast.show()

Basic Usage

Notification Types

Placement

Duration

Progress Bar

Pause on Hover

Toast.showCustom()

Toast.destroyAll()

Toast.defaults

API Reference

Toast options

Inherited from DialogProps

ToastSlots

Return Value