Toast

A component for displaying brief, temporary notifications.

Toasts are used to provide feedback to users about an action they have taken. They appear temporarily and should not interrupt the user's workflow.

Import

To use toasts, you need to import ToastProvider, useToast, and Button (or another trigger component).

import { ToastProvider, useToast, Button } from 'h2o-library';

Setup

To enable toasts throughout your application, wrap your root layout or a parent component with ToastProvider.

// In your layout.tsx or a top-level component
import { ToastProvider } from 'h2o-library';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ToastProvider>{children}</ToastProvider>
      </body>
    </html>
  );
}

Usage

Use the useToast hook within a component to get access to the showToast function. This function can be called to display a toast notification.

"use client";

import React from "react";
import { Button, useToast, ToastProvider } from "h2o-library";

function ToastExample() {
  const showToast = useToast();

  return (
    <div className="flex gap-6">
      <Button 
        variant="primary" 
        label="Info" 
        onClick={() => showToast({ variant: 'info', title: 'Info', description: 'This is an informational message.' })}
      />
      <Button 
        variant="success" 
        label="Success" 
        onClick={() => showToast({ variant: 'success', title: 'Success!', description: 'The action was completed successfully.' })}
      />
      <Button 
        variant="danger" 
        label="Error" 
        onClick={() => showToast({ variant: 'error', title: 'Error', description: 'Something went wrong.' })}
      />
      <Button 
        variant="warning" 
        label="Warning" 
        onClick={() => showToast({ variant: 'warning', title: 'Warning', description: 'Please be cautious.' })}
      />
    </div>
  );
}

// Wrap with provider for standalone example
const ToastExampleWithProvider = () => (
  <ToastProvider>
    <ToastExample />
  </ToastProvider>
);

Variants

Toasts come in four variants to reflect different types of messages.

  • Info: For general information.
  • Success: To confirm that an action was successful.
  • Error: To indicate that an error has occurred.
  • Warning: To warn the user about a potential issue.

With Actions

You can include primary and secondary actions in a toast.

const showToast = useToast();

showToast({
  variant: "success",
  title: "Success",
  description: "Your changes have been saved successfully.",
  primaryAction: {
    label: "View Changes",
    action: () => {
      // Handle primary action
    },
  },
  secondaryAction: {
    label: "Cancel",
    action: () => {
      // Handle secondary action
    },
  },
});

showToast Options

The showToast function accepts an object with the following properties:

PropTypeRequiredDescription
variant"info" | "success" | "error" | "warning"YesThe visual style of the toast.
titlestringYesThe title of the toast message.
descriptionstringYesThe main content of the toast message.
primaryAction{ label: string, action: () => void }NoThe main call-to-action button in the toast.
secondaryAction{ label: string, action: () => void }NoAn alternative action button in the toast.

Accessibility

  • Toasts are announced by screen readers automatically using ARIA live regions.
  • Toasts are designed to be non-intrusive and do not steal focus.
  • Ensure that toast messages are clear and concise.