Toast

A cross-platform React toast notification system for displaying brief, auto-dismissing messages. Includes a provider, hook API, and support for multiple toast variants.

Installation

npm install @xsolla/xui-toast
# or
yarn add @xsolla/xui-toast

Demo

Basic Setup (React Web)

Wrap your application with ToastProvider:

import * as React from 'react';
import { ToastProvider } from '@xsolla/xui-toast';

export default function App() {
  return (
    <ToastProvider>
      <YourApp />
    </ToastProvider>
  );
}

Basic Setup (React Native)

For React Native, wrap your app entry point with both XUIProvider and ToastProvider:

import React from 'react';
import { View } from 'react-native';
import { XUIProvider } from '@xsolla/xui-core';
import { ToastProvider } from '@xsolla/xui-toast';
import { MainNavigator } from './navigation';

export default function App() {
  return (
    <XUIProvider mode="dark">
      <ToastProvider position="top">
        <View style={{ flex: 1 }}>
          <MainNavigator />
        </View>
      </ToastProvider>
    </XUIProvider>
  );
}

Important for React Native: The ToastProvider renders toasts using absolute positioning. Ensure your app's root container has flex: 1 so toasts position correctly relative to the screen.

Showing Toasts (React Web)

Use the useToast hook to show toasts:

import * as React from 'react';
import { useToast } from '@xsolla/xui-toast';

export default function ToastExample() {
  const toast = useToast();

  return (
    <div style={{ display: 'flex', gap: 8 }}>
      <button onClick={() => toast.success('Quest has been activated')}>
        Success
      </button>
      <button onClick={() => toast.info('You received 50 Xsolla Points')}>
        Info
      </button>
      <button onClick={() => toast.warning('Your session is about to expire')}>
        Warning
      </button>
      <button onClick={() => toast.error('Failed to save changes')}>
        Error
      </button>
    </div>
  );
}

Showing Toasts (React Native)

The useToast hook works identically in React Native. Use onPress instead of onClick:

import React from 'react';
import { View } from 'react-native';
import { Button } from '@xsolla/xui-button';
import { useToast } from '@xsolla/xui-toast';

export default function ToastExample() {
  const toast = useToast();

  return (
    <View style={{ gap: 8 }}>
      <Button onPress={() => toast.success('Quest has been activated')}>
        Success
      </Button>
      <Button onPress={() => toast.info('You received 50 Xsolla Points')}>
        Info
      </Button>
      <Button onPress={() => toast.warning('Your session is about to expire')}>
        Warning
      </Button>
      <Button onPress={() => toast.error('Failed to save changes')}>
        Error
      </Button>
    </View>
  );
}

Toast Variants

import * as React from 'react';
import { Toast } from '@xsolla/xui-toast';

export default function ToastVariants() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, maxWidth: 400 }}>
      <Toast id="1" variant="success" message="Quest has been activated" onClose={() => {}} />
      <Toast id="2" variant="info" message="You received 50 Xsolla Points" onClose={() => {}} />
      <Toast id="3" variant="warning" message="Your session is about to expire" onClose={() => {}} />
      <Toast id="4" variant="error" message="Failed to save changes" onClose={() => {}} />
    </div>
  );
}

Custom Duration

import * as React from 'react';
import { useToast } from '@xsolla/xui-toast';

export default function CustomDuration() {
  const toast = useToast();

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <button onClick={() => toast.toast({ message: 'Stays for 10 seconds', duration: 10000 })}>
        Long Duration (10s)
      </button>
      <button onClick={() => toast.toast({ message: 'Stays for 2 seconds', duration: 2000 })}>
        Short Duration (2s)
      </button>
      <button onClick={() => toast.toast({ message: 'Dismiss me manually', duration: 0 })}>
        No Auto-Dismiss
      </button>
    </div>
  );
}

Dismissing Toasts

import * as React from 'react';
import { useToast } from '@xsolla/xui-toast';

export default function DismissExample() {
  const toast = useToast();
  const [lastToastId, setLastToastId] = React.useState<string | null>(null);

  const showToast = () => {
    const id = toast.info('New notification');
    setLastToastId(id);
  };

  return (
    <div style={{ display: 'flex', gap: 8 }}>
      <button onClick={showToast}>Show Toast</button>
      <button onClick={() => lastToastId && toast.dismiss(lastToastId)}>
        Dismiss Last
      </button>
      <button onClick={() => toast.dismissAll()}>Dismiss All</button>
    </div>
  );
}

Position Configuration

import * as React from 'react';
import { ToastProvider, useToast } from '@xsolla/xui-toast';

function ToastTrigger() {
  const toast = useToast();
  return <button onClick={() => toast.info('Toast at the bottom!')}>Show Toast</button>;
}

export default function BottomPosition() {
  return (
    <ToastProvider position="bottom">
      <ToastTrigger />
    </ToastProvider>
  );
}

API Reference

ToastProvider

The root provider component that manages toast state and renders the toast container.

ToastProvider Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | children | ReactNode | - | Application content. | | position | "top" \| "bottom" | "top" | Position of the toast container. | | defaultDuration | number | 5000 | Default auto-dismiss duration in milliseconds. |

useToast

A hook that provides methods to show and dismiss toasts. Must be used within a ToastProvider.

useToast Return Value:

| Method | Signature | Description | | :----- | :-------- | :---------- | | toast | (options: ToastOptions) => string | Show a toast with custom options. Returns the toast ID. | | success | (message: string, options?) => string | Show a success toast. | | info | (message: string, options?) => string | Show an info toast. | | warning | (message: string, options?) => string | Show a warning toast. | | error | (message: string, options?) => string | Show an error toast. | | dismiss | (id: string) => void | Dismiss a specific toast by ID. | | dismissAll | () => void | Dismiss all toasts. |

Toast

The individual toast component. Typically used internally by ToastProvider, but can be used standalone.

Toast Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | id | string | - | Unique toast identifier. | | message | string | - | Toast message text. | | variant | "success" \| "info" \| "warning" \| "error" | "info" | Toast variant/style. | | icon | ReactNode | - | Custom icon (optional, uses default icons per variant). | | onClose | () => void | - | Callback when close button is clicked. If not provided, close button is hidden. |

ToastOptions

Options passed to the toast() method.

| Property | Type | Default | Description | | :------- | :--- | :------ | :---------- | | message | string | - | Toast message text. | | variant | "success" \| "info" \| "warning" \| "error" | "info" | Toast variant. | | icon | ReactNode | - | Custom icon. | | duration | number | Provider's defaultDuration | Auto-dismiss duration. Use 0 to disable auto-dismiss. |

Variant Values

| Variant | Use Case | Default Icon | | :------ | :------- | :----------- | | success | Positive outcomes, confirmations | Check circle | | info | General information, neutral messages | Info circle | | warning | Caution, requires attention | Alert circle | | error | Errors, failures, critical issues | Alert circle |

Theming

Toast uses the inverse color scheme (dark background with light text):

// Toast styling accessed via theme
theme.colors.background.inverse  // Toast background (black)
theme.colors.content.inverse     // Toast text (white)

// Variant-specific icon colors
theme.colors.content.success.primary  // Success icon
theme.colors.content.warning.primary  // Warning icon
theme.colors.content.alert.primary    // Error icon

Platform Support

This package supports both React (web) and React Native with identical API:

React (Web)

• Uses ReactDOM.createPortal for fixed positioning at the document body level
• Toasts appear above all other content regardless of z-index stacking context
• Works with any React web framework (Next.js, Vite, Create React App, etc.)

React Native

• Uses absolute positioning within the app container
• Toasts render within the component tree (no portal equivalent in RN)
• Works with React Navigation, Expo, and bare React Native projects

Cross-Platform Usage Notes

| Feature | Web | React Native | | :------ | :-- | :----------- | | Provider setup | Wrap with ToastProvider | Wrap with XUIProvider + ToastProvider | | Hook API | useToast() | useToast() (identical) | | Event handlers | onClick (optional) | onPress | | Root container | Any element | Must have flex: 1 | | Position: top | Fixed to viewport top | Absolute to container top | | Position: bottom | Fixed to viewport bottom | Absolute to container bottom |

React Native Example with Navigation

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { XUIProvider } from '@xsolla/xui-core';
import { ToastProvider } from '@xsolla/xui-toast';
import { RootNavigator } from './navigation';

export default function App() {
  return (
    <SafeAreaProvider>
      <XUIProvider mode="dark">
        <ToastProvider position="top">
          <NavigationContainer>
            <RootNavigator />
          </NavigationContainer>
        </ToastProvider>
      </XUIProvider>
    </SafeAreaProvider>
  );
}

Accessibility

• Toasts use role="alert" and aria-live="polite" for screen reader announcements
• Close button includes aria-label="Dismiss toast"
• Icons are decorative and do not affect accessibility
• Keyboard users can dismiss toasts via the close button