Toasts · Pixel UI component · LumeSec Elements

<PxToaster />· loading

Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

Loading <PxToaster />

Props

maxlive

React

<PxToaster max={4} />

Installation

pnpm dlx shadcn@latest add @lumesec/px-toaster

First timeRegister the @lumesec registry once, or install by URL+

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/px-toaster.json

Usage

px-toaster-example.tsx

import * as React from "react";

import { PxToaster, type PxToasterHandle } from "@/components/lumesec/px-toaster";

export function Example() {
  const toaster = React.useRef<PxToasterHandle>(null);
  return (
    <>
      <button type="button" onClick={() => toaster.current?.show({ title: "Changes saved", type: "success" })}>
        Save
      </button>
      <PxToaster ref={toaster} position="bottom-right" />
    </>
  );
}

Behaviour

Stacked notifications with pixel icons and a draining timer that pauses while you hover. Add position="bottom-right" to pin it to the viewport.

API reference

Props

Also accepts every prop of <div> (React.ComponentProps<"div">), spread onto the root element.

positionType"bottom-right" | "bottom-left" | "top-right"

Pins the stack to that viewport corner with position: fixed, up to 360 px wide. Without it the stack stays in the flow.

maxTypenumberDefault4

Maximum toasts on screen; showing one more dismisses the oldest.

onShowType(id: number, type: PxToastType) => void

Called when a toast is added.

onDismissType(id: number) => void

Called when a toast starts leaving: timer, dismiss button, action button, overflow or dismiss().

Ref

ref receives a PxToasterHandle handle with these methods.

show(toast?: PxToastOptions): number

Adds a toast and returns its id. PxToastOptions is { title?: React.ReactNode; description?: React.ReactNode; type?: "info" | "success" | "warning" | "error"; duration?: number; action?: { label: string; onClick?: () => void } }. type defaults to info and duration to 4500 ms; 0 or less keeps the toast until dismissed. The action button calls onClick and dismisses the toast.

dismiss(id: number): void

Starts the exit of the toast with that id. Unknown or leaving ids are ignored.

Accessibility

The stack is a role="region" with aria-label="Notifications" and aria-live="polite".
Each toast has role="status"; error toasts have role="alert".
Dismiss buttons are native buttons labelled "Dismiss"; action buttons use the action label.
Hover or focus inside the stack pauses all timers.
The type icons and timer bars are drawn on an aria-hidden canvas.
Reduced motion: toasts appear and leave without the slide and collapse animations; the timer bars still drain.

Theming

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --card, --border, --foreground, --muted-foreground, --muted, --lumesec, --lumesec-success, --lumesec-warning and --destructive.

Notes

Toasts appear only through show() on the handle; ref is the handle, not the DOM element.
Pinning uses position: fixed on the root, so an ancestor that creates a containing block for fixed-position descendants (for example through filter or transform) changes what it is fixed to.

<px-button>

Async buttonpx-button

<px-confirm>

Two-step deletepx-confirm

<px-progress>

Progress barpx-progress

<px-ring>

Progress ringpx-ring

Related