FlashMessages

Global toast/notification host. FlashMessages is mounted once near the app root; anywhere else in the app you push notifications imperatively with flashMessage(...) — no props or React context are threaded through the tree.

When to use

Use for transient, app-wide feedback ("Saved", "Something went wrong") triggered from event handlers, services, or async flows. Because it is driven by a module-level singleton ref, you can call it from non-React code too.

For inline, in-layout status blocks, use InfoBox or AnnouncementBar.
For confirm/alert dialogs, use ModalDialog.

There is no @uxf/form twin.

Usage

Mount the host once (e.g. in _app.tsx) and wire it to the shared ref:

import { FlashMessages, getFlashMessagesRef } from "@uxf/ui/flash-messages";

function App(props: AppProps) {
    return (
        <>
            {props.children}
            <FlashMessages ref={getFlashMessagesRef()} />
        </>
    );
}

Trigger messages from anywhere:

import { flashMessage } from "@uxf/ui/flash-messages";

// success is the default variant, auto-dismisses after 5s
flashMessage({ message: <span>Everything is alright.</span> });

flashMessage({ message: <span>Error message.</span>, variant: "error" });

// permanent message — stays until the user (or closeAll) dismisses it
flashMessage({ message: "Just letting you know", autoDismiss: false, variant: "info" });

API

Import path: @uxf/ui/flash-messages.

Export	Kind	Signature	Description
`FlashMessages`	component	`forwardRef<FlashMessagesRef>`	The host to mount once. Renders nothing when there are no active notifications.
`flashMessage`	function	`(notification: Notification) => void`	Opens a notification via the shared ref. No-op if the host is not mounted.
`getFlashMessagesRef`	function	`() => RefObject<FlashMessagesRef>`	Returns the shared singleton ref to pass to `FlashMessages`.
`FlashMessagesRef`	type	`{ open(n); close(n); closeAll() }`	Imperative handle exposed by the host.

`Notification`

The object passed to flashMessage (the Notification type itself is not exported):

Field	Type	Default	Description
`message`	`ReactNode`	— (required)	Content to display.
`variant`	`"success" \| "error" \| "info" \| "warning"`	`"success"`	Visual style.
`autoDismiss`	`boolean`	`true`	When `true`, dismisses after `dismissTimeout`. When `false`, the message is permanent.
`dismissTimeout`	`number`	`5000`	Auto-dismiss delay in milliseconds.
`id`	`number`	random	Key for the notification; auto-generated when omitted.

Variants & states

Auto-dismiss vs. permanent: auto-dismiss toasts are grouped into a stack that expands on hover; permanent ones (autoDismiss: false) render in a separate group and a divider appears between the groups when needed.
Dismiss: clicking a message closes it. FlashMessagesRef.closeAll() clears all at once.

Requirements

Client component (uses @headlessui/react transitions and "use client").
Mount exactly one <FlashMessages ref={getFlashMessagesRef()} /> in the app; flashMessage is a no-op until it is mounted.
Import the component stylesheet once in your global CSS:
```
@import url("@uxf/ui/css/flash-messages.css");
```
Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.

Default

Open in new tab

OnlyForE2ETests

Open in new tab

When to use

For inline, in-layout status blocks, use InfoBox or AnnouncementBar.

For confirm/alert dialogs, use ModalDialog.

There is no @uxf/form twin.

Usage

Mount the host once (e.g. in _app.tsx) and wire it to the shared ref:

import { FlashMessages, getFlashMessagesRef } from "@uxf/ui/flash-messages"; function App(props: AppProps) { return ( <> {props.children} <FlashMessages ref={getFlashMessagesRef()} /> </> ); }

Trigger messages from anywhere:

import { flashMessage } from "@uxf/ui/flash-messages"; // success is the default variant, auto-dismisses after 5s flashMessage({ message: <span>Everything is alright.</span> }); flashMessage({ message: <span>Error message.</span>, variant: "error" }); // permanent message — stays until the user (or closeAll) dismisses it flashMessage({ message: "Just letting you know", autoDismiss: false, variant: "info" });

API

Import path: @uxf/ui/flash-messages.

Export

Kind

Signature

Description

FlashMessages

component

forwardRef<FlashMessagesRef>

The host to mount once. Renders nothing when there are no active notifications.

flashMessage

function

(notification: Notification) => void

Opens a notification via the shared ref. No-op if the host is not mounted.

getFlashMessagesRef

function

() => RefObject<FlashMessagesRef>

Returns the shared singleton ref to pass to FlashMessages.

FlashMessagesRef

type

{ open(n); close(n); closeAll() }

Imperative handle exposed by the host.

Notification

The object passed to flashMessage (the Notification type itself is not exported):

Field

Type

Default

Description

message

ReactNode

— (required)

Content to display.

variant

"success" | "error" | "info" | "warning"

"success"

Visual style.

autoDismiss

boolean

true

When true, dismisses after dismissTimeout. When false, the message is permanent.

dismissTimeout

number

5000

Auto-dismiss delay in milliseconds.

id

number

random

Key for the notification; auto-generated when omitted.

Variants & states

Auto-dismiss vs. permanent: auto-dismiss toasts are grouped into a stack that expands on hover; permanent ones (autoDismiss: false) render in a separate group and a divider appears between the groups when needed.

Dismiss: clicking a message closes it. FlashMessagesRef.closeAll() clears all at once.

Requirements

Client component (uses @headlessui/react transitions and "use client").

Mount exactly one <FlashMessages ref={getFlashMessagesRef()} /> in the app; flashMessage is a no-op until it is mounted.

Import the component stylesheet once in your global CSS:

@import url("@uxf/ui/css/flash-messages.css");

Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.