Toast

Toasts are short, non-blocking notifications that appear in a corner and close themselves. Call useToast() anywhere below a JarvisProvider (or ToastProvider) to show one.

import { Toast } from 'jarvis-react-ui';

Show a toast

toast(options) shows a notification and returns its id. The four variants change the color, the icon and the sound: success plays confirm, error plays error.

import { Button, useToast } from 'jarvis-react-ui';

export default function Variants() {
    const { toast } = useToast();

    return (
        <>
            <Button onClick={() => toast({ title: 'Uplink established' })}>Info</Button>
            <Button onClick={() => toast({ variant: 'success', title: 'Diagnostics passed' })}>
                Success
            </Button>
            <Button onClick={() => toast({ variant: 'warning', title: 'Power at 18%' })}>
                Warning
            </Button>
            <Button
                variant="danger"
                onClick={() => toast({ variant: 'error', title: 'Connection lost' })}
            >
                Error
            </Button>
        </>
    );
}

import { useToast } from 'jarvis-react-ui';

const { toast } = useToast();
toast({ variant: 'success', title: 'Diagnostics passed' });

Title and description

Keep the title to a few words and put details in description.

import { Button, useToast } from 'jarvis-react-ui';

export default function WithDescription() {
    const { toast } = useToast();

    return (
        <Button
            variant="primary"
            onClick={() =>
                toast({
                    variant: 'success',
                    title: 'Profile saved',
                    description: 'Your changes are synced to all devices.',
                })
            }
        >
            Save profile
        </Button>
    );
}

Action

An action adds a button, typically Undo. Clicking it runs the handler and closes the toast.

import { useState } from 'react';
import { Button, Pill, useToast } from 'jarvis-react-ui';

export default function WithAction() {
    const { toast } = useToast();
    const [archived, setArchived] = useState(false);

    function archive() {
        setArchived(true);
        toast({
            title: 'Log archived',
            action: { label: 'Undo', onClick: () => setArchived(false) },
        });
    }

    return (
        <>
            <Button onClick={archive} disabled={archived}>
                Archive log
            </Button>
            <Pill variant={archived ? 'warn' : 'ok'}>{archived ? 'archived' : 'active'}</Pill>
        </>
    );
}

Duration

Toasts close after 5 seconds by default; the bar at the bottom shows the remaining time. The timer pauses while the pointer is over the toast or focus is inside it. Pass duration: Infinity for messages that must be dismissed by hand, and dismiss(id) to close one from code.

import { Button, useToast } from 'jarvis-react-ui';

export default function Duration() {
    const { toast, dismiss } = useToast();

    return (
        <>
            <Button onClick={() => toast({ title: 'Quick notice', duration: 1500 })}>1.5 s</Button>
            <Button
                onClick={() =>
                    toast({
                        id: 'reactor',
                        variant: 'error',
                        title: 'Reactor offline',
                        description: 'Stays until dismissed.',
                        duration: Infinity,
                    })
                }
            >
                Sticky
            </Button>
            <Button variant="ghost" onClick={() => dismiss('reactor')}>
                Dismiss sticky
            </Button>
        </>
    );
}

Reusing an id replaces the visible toast instead of stacking a new one, which suits repeated events such as "Copied". This site does exactly that when you copy a code block.

The Toast element

Toast is the presentational element the provider renders. Use it directly to build your own notification area or to show a toast inline. It does not close itself; duration only draws the countdown bar.

import { Toast } from 'jarvis-react-ui';

export default function Static() {
    return (
        <div className="flex w-full max-w-[360px] flex-col gap-2">
            <Toast
                variant="success"
                title="Diagnostics passed"
                description="All systems nominal."
                duration={5000}
                paused
                onDismiss={() => undefined}
            />
            <Toast
                variant="warning"
                title="Power at 18%"
                action={{ label: 'Reroute', onClick: () => undefined }}
            />
        </div>
    );
}

Options

Every option is optional. Pass at least a title or a description; one of them is enough.

useToast() returns { toast, dismiss, dismissAll } and throws when no provider is mounted. Placement, the number of visible toasts and the default duration are set on ToastProvider or JarvisProvider.

Accessibility

• Toasts render inside a labelled aria-live="polite" region, so screen readers announce them without moving focus.
• Toasts use role="status"; error toasts use role="alert" and are announced immediately.
• The timer pauses on hover and keyboard focus, and Escape closes the focused toast.
• Do not put information only in a toast that the user cannot find again elsewhere.

API

Also accepts inherited props from HTMLAttributes (53), AriaAttributes (53), DOMAttributes (170), RefAttributes (1), Attributes (1).

Type ToastAction

Action button shown in a toast, e.g. { label: 'Undo', onClick: undo }.