B2C Toast

A B2C toast notification system that extends the base toast structure with B2C floating surface colors. The API mirrors @xsolla/xui-toast: title, optional description, optional action, optional progress, and provider-based stacking.

Installation

npm install @xsolla/xui-b2c-toast

Imports

import {
  Toast,
  ToastProvider,
  ToastGroup,
  ToastContext,
  useToast,
  type ToastProps,
  type ToastOptions,
  type ToastType,
  type ToastPosition,
  type ToastAlign,
  type UseToastReturn,
} from "@xsolla/xui-b2c-toast";

Quick start

Wrap your app with ToastProvider, then call useToast from any descendant.

import * as React from "react";
import { XUIProvider } from "@xsolla/xui-core";
import { ToastProvider, useToast } from "@xsolla/xui-b2c-toast";

function SaveButton() {
  const toast = useToast();
  return (
    <button onClick={() => toast.success({ title: "Saved successfully" })}>
      Save
    </button>
  );
}

export default function App() {
  return (
    <XUIProvider initialMode="dark">
      <ToastProvider>
        <SaveButton />
      </ToastProvider>
    </XUIProvider>
  );
}

API Reference

<ToastProvider>

Root provider. Manages toast state, auto-dismiss timers, and renders the ToastGroup.

| Prop | Type | Default | Description | | ----------------- | ------------------------------- | ---------- | -------------------------------------------------------------- | | children | ReactNode | - | Application content. | | position | "top" \| "bottom" | "top" | Vertical anchor of the toast container. | | align | "left" \| "center" \| "right" | "center" | Horizontal alignment of toasts within the container. | | defaultDuration | number | 5000 | Default auto-dismiss duration in ms. Set 0 to disable. | | maxWidth | number | - | Maximum width in px of the toast stack. | | testID | string | - | Test ID for web and React Native testing frameworks. |

<Toast>

The individual toast cell. Used internally by ToastGroup, but can be rendered standalone for static display.

| Prop | Type | Default | Description | | ----------------- | ------------------------------------------------ | ----------- | ------------------------------------------------------------------ | | id | string | - | Required unique identifier. | | type | "alert" \| "success" \| "neutral" \| "warning" | "neutral" | Visual and accessibility type. | | title | string | - | Short primary text, ideally 1 to 5 words. | | description | string | - | Optional supporting text. | | icon | boolean \| ReactNode | true | Show the default icon, hide it with false, or pass a custom one. | | action | ReactElement | - | Optional action element, typically a FlexButton. | | showCloseButton | boolean | true | Show the trailing dismiss control when onClose is provided. | | progress | boolean | false | Show the bottom progress strip. | | duration | number | - | Auto-dismiss duration in ms. 0 or omitted = no auto-dismiss. | | onClose | () => void | - | Close handler. Required for the close button to render. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

<ToastGroup>

Renders the stack of visible toasts using the B2C toast surface. On web it uses a portal to escape local stacking contexts; on React Native it renders with absolute positioning.

| Prop | Type | Default | Description | | ----------- | ------------------------------- | ---------- | --------------------------- | | toasts | ToastData[] | - | Toasts to render. | | position | "top" \| "bottom" | "top" | Vertical anchor. | | align | "left" \| "center" \| "right" | "center" | Horizontal alignment. | | maxWidth | number | - | Maximum width in px. | | onDismiss | (id: string) => void | - | Dismiss callback per toast. |

Inherits ThemeOverrideProps.

ToastContext

React context used by ToastProvider and useToast to share the active toast list and dismissal helpers.

useToast()

Hook that returns toast helpers. Throws if called outside a ToastProvider.

| Method | Signature | Description | | ------------ | ------------------------------------------------- | ----------------------------------------------------- | | toast | (options: ToastOptions) => string | Show a toast with full options. Returns the toast ID. | | alert | (options: Omit<ToastOptions, "type">) => string | Show an alert toast. | | success | (options: Omit<ToastOptions, "type">) => string | Show a success toast. | | neutral | (options: Omit<ToastOptions, "type">) => string | Show a neutral toast. | | warning | (options: Omit<ToastOptions, "type">) => string | Show a warning toast. | | dismiss | (id: string) => void | Dismiss a specific toast by ID. | | dismissAll | () => void | Dismiss all visible toasts. |

Examples

Types

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

export default function Types() {
  const toast = useToast();
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <button onClick={() => toast.neutral({ title: "Reward claimed" })}>
        Neutral
      </button>
      <button onClick={() => toast.success({ title: "Quest activated" })}>
        Success
      </button>
      <button onClick={() => toast.warning({ title: "Session expires soon" })}>
        Warning
      </button>
      <button onClick={() => toast.alert({ title: "Connection lost" })}>
        Alert
      </button>
    </div>
  );
}

Standalone Toast With Action

import * as React from "react";
import { FlexButton } from "@xsolla/xui-button";
import { Toast } from "@xsolla/xui-b2c-toast";

export default function Standalone() {
  return (
    <Toast
      id="retry"
      type="alert"
      title="Connection lost"
      description="Check your network and try again"
      action={<FlexButton>Retry</FlexButton>}
      onClose={() => {}}
    />
  );
}

Theme

• In light mode, B2C toast uses layer/float-style white translucency, primary black title text, secondary black description text, and popover shadow.
• In dark mode, B2C toast uses a dark floating surface with static-light title/action text and muted static-light description text.
• Layout, icons, divider, close button, action slot, progress strip, provider behavior, and accessibility semantics are inherited from the base toast implementation.

Accessibility

• Neutral and success toasts render with role="status" and polite announcements.
• Warning and alert toasts render with role="alert" and assertive announcements.
• The close button has aria-label="Dismiss notification".