Toast

Toast displays a temporary notification about an action or event.

Examples

Properties

Hooks

Playground

Basics

Call toast.success with a title and message to show a standard confirmation toast.

Loading demo…

import { Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  return (
    <Button
      onPress={() =>
        toast.success({
          title: 'Success!',
          message: 'The operation finished without issues.',
        })
      }
    >
      Show success toast
    </Button>
  );
}

Positions

Set the position option to anchor the toast stack to any corner or edge of the viewport.

Loading demo…

import { Button, Row, useToast } from '@plocks/ui';

const toastPositions = [
  'top-left',
  'top-center',
  'top-right',
  'bottom-left',
  'bottom-center',
  'bottom-right',
] as const;

export function Demo() {
  const toast = useToast();

  const showToastAtPosition = (position: typeof toastPositions[number]) => {
    toast.show({
      title: `Toast at ${position}`,
      message: `This toast appears at ${position} position.`,
      position,
    });
  };

  return (
    <Row gap="xs" wrap="wrap">
      {toastPositions.map((position) => (
        <Button key={position} size="sm" onPress={() => showToastAtPosition(position)}>
          {position}
        </Button>
      ))}
    </Row>
  );
}

Visual Variants

Use the variant prop to control the toast surface: filled (solid color with auto-contrast text), outline (surface with a full colored border), or light (subtle surface with a colored left accent). Combine it with any color or severity helper.

Loading demo…

import { Block, Icon, Text, Toast } from '@plocks/ui';

const VARIANTS = ['light', 'filled', 'outline'] as const;

export function Demo() {
  return (
    <Block gap="md">
      {VARIANTS.map((variant) => (
        <Block key={variant} gap="xs">
          <Text variant="small" c="secondary">
            {variant}
          </Text>
          <Toast
            visible
            variant={variant}
            severity="success"
            title="Changes saved"
            icon={<Icon name="success" variant="filled" />}
            withCloseButton={false}
          >
            Your profile has been updated.
          </Toast>
        </Block>
      ))}
    </Block>
  );
}

Size Tokens

The size prop supports the full seven-token scale (xs, sm, md, lg, xl, 2xl, 3xl) and scales padding, title and body typography, the leading icon, action buttons, and the close button together. A number is read as the title font size and scales the rest proportionally. Set defaultSize on ToastProvider to change the default for every toast.

Loading demo…

import { Block, Icon, Text, Toast } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block gap="md">
      {SIZES.map((size) => (
        <Block key={size} gap="xs">
          <Text variant="small" c="secondary">
            {size}
          </Text>
          <Toast
            visible
            size={size}
            severity="info"
            title="Sync complete"
            icon={<Icon name="info" variant="filled" />}
            withCloseButton={false}
          >
            Everything is up to date.
          </Toast>
        </Block>
      ))}
    </Block>
  );
}

Severity Helpers

Use toast.success, toast.warning, toast.error, and toast.info to render consistent styling and icons for each severity.

Loading demo…

import { Button, Row, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  const showSuccessToast = () => {
    toast.success({
      title: 'Success',
      message: 'The request completed correctly.',
    });
  };

  const showWarningToast = () => {
    toast.warning({
      title: 'Warning',
      message: 'Double-check the highlighted fields.',
    });
  };

  const showErrorToast = () => {
    toast.error({
      title: 'Error',
      message: 'Something went wrong.',
    });
  };

  const showInfoToast = () => {
    toast.info({
      title: 'Info',
      message: 'Here is some additional context.',
    });
  };

  return (
    <Row gap="xs" wrap="wrap">
      <Button onPress={showSuccessToast} variant="filled" color="success">
        Success
      </Button>
      <Button onPress={showWarningToast} variant="filled" color="warning">
        Warning
      </Button>
      <Button onPress={showErrorToast} variant="filled" color="error">
        Error
      </Button>
      <Button onPress={showInfoToast} variant="outline">
        Info
      </Button>
    </Row>
  );
}

Interactive Features

Add actions, toggle persistent, or shorten autoHide to tailor toast interactions for acknowledgements, warnings, and ephemeral notices.

Loading demo…

import { Block, Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  const showActionToast = () => {
    toast.show({
      title: 'File uploaded',
      message: 'Your file has been uploaded successfully.',
      actions: [
        {
          label: 'Undo',
          onPress: () => toast.info('Upload reverted'),
        },
      ],
    });
  };

  const showPersistentToast = () => {
    toast.show({
      title: 'Important notice',
      message: 'This toast stays visible until dismissed.',
      persistent: true,
    });
  };

  const showTimedToast = () => {
    toast.show({
      title: 'Quick message',
      message: 'This one hides after two seconds.',
      autoHide: 2000,
    });
  };

  return (
    <Block>
      <Button onPress={showActionToast}>Toast with action</Button>
      <Button variant="outline" onPress={showPersistentToast}>
        Persistent toast
      </Button>
      <Button variant="outline" onPress={showTimedToast}>
        Quick toast (2s)
      </Button>
    </Block>
  );
}

Stacking

Toasts at the same position form a stack. The newest one always takes the slot against the anchored edge and the rest move out of its way; when one is dismissed, the toasts behind it slide into the gap while it fades. Hovering — or tabbing into — any toast pauses the countdown on the whole stack, and resumes it with the time that was left. limit caps how many are on screen at once, retiring the oldest with its normal exit rather than deleting it.

Loading demo…

import { useRef } from 'react';

import { Block, Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();
  const counter = useRef(0);

  const push = () => {
    counter.current += 1;
    const n = counter.current;
    toast.show({
      title: `Message ${n}`,
      message: 'Dismiss one from the middle to watch the stack close the gap.',
      severity: (['info', 'success', 'warning', 'error'] as const)[n % 4],
      autoHide: 6000,
    });
  };

  const pushBurst = () => {
    toast.batch(
      Array.from({ length: 5 }, (_, index) => ({
        title: `Burst ${index + 1}`,
        message: 'Five at once — the limit retires the oldest.',
        severity: 'info' as const,
      }))
    );
  };

  return (
    <Block>
      <Button onPress={push}>Add a toast</Button>
      <Button variant="outline" onPress={pushBurst}>
        Add five at once
      </Button>
    </Block>
  );
}

Enhanced Features

Combine swipe gestures, custom animationConfig, batch helpers, and toast.promise to coordinate rich toast experiences.

Loading demo…

import { Block, Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  const showSwipeableToast = () => {
    toast.info({
      title: 'Swipe me!',
      message: 'Drag in any direction to dismiss this toast.',
      swipeConfig: { direction: 'both', threshold: 150 },
    });
  };

  const showAnimatedToast = () => {
    toast.success({
      title: 'Spring motion',
      message: 'Bounce animation with custom spring physics.',
      animationConfig: {
        type: 'bounce',
        springConfig: { damping: 10, stiffness: 100 },
      },
    });
  };

  const showBatchToasts = () => {
    toast.batch([
      { title: 'Batch 1', message: 'First toast in batch', severity: 'info' },
      { title: 'Batch 2', message: 'Second toast in batch', severity: 'success' },
      { title: 'Batch 3', message: 'Third toast in batch', severity: 'warning' },
    ]);
  };

  const showPromiseToast = () => {
    toast.promise(new Promise((resolve) => setTimeout(resolve, 2000)), {
      pending: 'Loading data…',
      success: 'Data loaded',
      error: 'Could not load data',
    });
  };

  return (
    <Block>
      <Button onPress={showSwipeableToast}>Swipe to dismiss</Button>
      <Button variant="outline" onPress={showAnimatedToast}>
        Bounce animation
      </Button>
      <Button variant="outline" onPress={showBatchToasts}>
        Show batch toasts
      </Button>
      <Button variant="outline" onPress={showPromiseToast}>
        Promise integration
      </Button>
    </Block>
  );
}

Text customization

titleProps and bodyProps accept any <Text> props (ff, fw, size, c, style…) and apply them to the toast title and body slots. Useful for matching toast typography to your brand.

Loading demo…

import { Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  return (
    <Button
      onPress={() =>
        toast.show({
          title: 'Bold uppercase title',
          message: 'Title rendered with monospace + tracking.',
          severity: 'success',
          titleProps: {
            ff: 'monospace',
            fw: '700',
            tt: 'uppercase',
            lts: 1,
            size: 'sm',
          },
          bodyProps: { size: 'sm' },
        })
      }
    >
      Show custom toast
    </Button>
  );
}

Scan to open this page on your phoneplocks.dev/ui/Toast

React Native design for iOS, Android, and Web.

Quick Links

Components Charts Hooks Add-ons & extensions

Docs

Getting Started Examples Localization Accessibility

Agents

llms.txt Skills Sitemap

Resources

FAQ Changelog Contributing