Skip to main content

useToast

useToast is a notification hook for showing brief messages, like confirming an export or announcing an active preview. It returns functions to show and hide notifications in the closest toast provider.

Import

import { useToast } from '@vortexlabs/vortex';

Features

  • Shows notifications in the closest ToastProvider.
  • Returns an ID to dismiss each notification.
  • Works inside VortexProvider without extra setup.

Usage

Call show from an event handler. Toast covers tones, actions, and positions.

"use client";

import { Button, useToast } from "@vortexlabs/vortex";

export const UseToastExample = () => {
  const toast = useToast();

  return (
    <Button
      onClick={() =>
        toast.show({
          title: "Export complete",
          description: "Your file is ready.",
          tone: "success",
        })
      }
    >
      Show notification
    </Button>
  );
};

Notification IDs

show returns an ID; pass it to hide to close that notification. timeout: 0 keeps it open until then.

"use client";

import { Button, useToast } from "@vortexlabs/vortex";
import { useEffect, useState } from "react";

export const UseToastIdExample = () => {
  const { show, hide } = useToast();
  const [notificationId, setNotificationId] = useState<string | null>(null);

  // Hides the notification when the preview ends or the component unmounts.
  useEffect(
    () => () => {
      if (notificationId) hide(notificationId);
    },
    [notificationId, hide],
  );

  return (
    <Button
      onClick={() =>
        setNotificationId(
          notificationId
            ? null
            : show({ title: "Preview mode is active", timeout: 0 }),
        )
      }
    >
      {notificationId ? "End preview" : "Start preview"}
    </Button>
  );
};

Provider Scope

Inside a nested ToastProvider, useToast sends notifications to that provider's queue.

"use client";

import { Button, Stack, ToastProvider, useToast } from "@vortexlabs/vortex";

const ScopedNotificationButton = () => {
  const toast = useToast();

  return (
    <Button
      variant="secondary"
      onClick={() =>
        toast.show({ title: "Local preview saved", position: "bottom-center" })
      }
    >
      Notify this preview
    </Button>
  );
};

export const UseToastScopeExample = () => {
  return (
    <Stack
      height="12rem"
      width="100%"
      align="start"
      attributes={{ style: { position: "relative" } }}
    >
      <ToastProvider options={{ "bottom-center": { width: "min(22rem, 100%)" } }}>
        <ScopedNotificationButton />
      </ToastProvider>
    </Stack>
  );
};