Toast

The Toast component is a notification element that displays brief messages to the user. It allows users to receive feedback about an operation or to display important information.

Installation

Every component ships with the boilerplate. If you are working in your own project, add Toast with the Gameface CLI:

npx gameface-cli add Toast

The CLI pulls in whatever Toast depends on. To refresh an existing copy, update it instead.

Usage

To include a toast in your UI, call the createToast function with the desired options and include the Toaster component in your JSX.

index.tsx

import useToast from '@components/Feedback/Toast/toast';

const App = () => {
    const [Toaster, createToast] = useToast();

    // Example of creating a toast
    const showToast = () => {
        createToast({
            body: () => <>This is a toast message</>,
            position: 'top-right', // Position of the toast on the screen
            timeout: 3000, // Duration in milliseconds before the toast disappears
        });
    };
    return (
        <>
            <button onClick={showToast}>Show Toast</button>
            <Toaster />
        </>
    );
};

API

createToast(options: ToastOptions)

Creates a new toast notification with the specified options.

Parameters

Option Name	Type	Default	Description
body	string | JSX.Element	""	The content of the toast message. Can be a string or JSX element.
position	'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'	'top-right'	The position on the screen where the toast will appear.
timeout	number	0	Duration in milliseconds before the toast disappears. 0 makes the toast persistent.

Body Arguments

When defining the body function, you receive the following helpers:

Argument	Type	Description
close	(children: JSX.Element) => JSX.Element	A wrapper function that attaches a click-to-close listener to any element.
progress	() => number	A signal returning the current lifetime of the toast (0 to 20).
dismiss	() => void	A function to programmatically remove the toast from the UI.

Guide

Adding a close button

To allow the user to close the toast manually you can include the Close button inside the body:

import useToast from '@components/Feedback/Toast/toast';

const App = () => {
    const [Toaster, createToast] = useToast();

    // Example of creating a toast
    const showToast = () => {
        createToast({
            body: (close) => (
                <>
                    This is a toast message
                    {close(<button>Close</button>)}
                </>
            ),
            position: 'top-right', // Position of the toast on the screen
            timeout: 3000, // Duration in milliseconds before the toast disappears
        });
    };
    return (
        <>
            <button onClick={showToast}>Show Toast</button>
            <Toaster />
        </>
    );
};

export default App;

Adding a progress bar

You can display a progress bar inside your toast by using the progress signal within the body function, together with the Progress.Bar component:

import useToast from '@components/Feedback/Toast/toast';
import Progress from '@components/Feedback/Progress/Progress';

const App = () => {
    const [Toaster, createToast] = useToast();

    // Example of creating a toast
    const showToast = () => {
        createToast({
            body: (close, progress) => (
                <>
                    This is a toast message
                    <div style={{ width: '100%', height: '5px', background: '#ccc' }}>
                        <Progress.Bar progress={progress() * 5} />
                    </div>
                    {close(<button>Close</button>)}
                </>
            ),
            position: 'top-right', // Position of the toast on the screen
            timeout: 3000, // Duration in milliseconds before the toast disappears
        });
    };

    return (
        <>
            <button onClick={showToast}>Show Toast</button>
            <Toaster />
        </>
    );
};
export default App;

Caution

If you try to use the progress signal outside the return of the body function, it will rerender the entire toast every time the progress updates, which can lead to performance issues.

Note

The progress signal returns a value between 0 and 20 to allow for smoother progress bar and to not harm performance. If you want to get a value between 0 and 100, you can multiply the value by 5.

Adding entrance animations

You can add entrance animations to the toast by adding CSS classes to the body element:

import useToast from '@components/Feedback/Toast/toast';

const App = () => {
    const [Toaster, createToast] = useToast();

    // Example of creating a toast
    const showToast = () => {
        createToast({
            body: (close) => (
                <div class="animate-fade-in">
                    This is a toast message
                    {close(<button>Close</button>)}
                </div>
            ),
            position: 'top-right', // Position of the toast on the screen
            timeout: 3000, // Duration in milliseconds before the toast disappears
        });
    };
    return (
        <>
            <button onClick={showToast}>Show Toast</button>
            <Toaster />
        </>
    );
};

export default App;

@keyframes fade-in {
    from {
        opacity: 0;
        transform: translateY(-10px);
    }
    to {
        opacity: 1;
        transform: translateY(0);
    }
}

.animate-fade-in {
    animation: fade-in 0.5s ease-out;
}

Programmatic Closing

While the close wrapper is convenient for standard buttons, you may need to close a toast programmatically after an logic-heavy action (like starting a tutorial or responding to a gamepad event). The dismiss function allows you to trigger the removal logic directly without relying on DOM click events.

import useToast from '@components/Feedback/Toast/toast';

const App = () => {
    const [Toaster, createToast] = useToast();

    const showToast = () => {
        createToast({
            body: (close, progress, dismiss) => (
                <div>
                    Proceed with Action?
                    <button onClick={() => {
                        // 1. Perform your logic
                        console.log("Action Triggered");

                        // 2. Programmatically close the toast
                        dismiss();
                    }}>
                        Confirm
                    </button>

                    {/* Fallback for simple UI closing */}
                    {close(<button>Cancel</button>)}
                </div>
            ),
            position: 'top-center',
            timeout: 0, // Persistent until dismissed
        });
    };

    return (
        <>
            <button onClick={showToast}>Trigger Complex Toast</button>
            <Toaster />
        </>
    );
};