Toast

A toast is a short message that appears over the app and clears itself. Mount a FossToaster once near the root, then call showFossToast from anywhere below it. Toasts stack at the bottom, at most three at a time, and each one carries a title, an optional description, a status glyph, and an optional action.

import 'package:fossui/fossui.dart';

FossToaster(child: MyApp());

With the toaster in place, raise a toast from any descendant:

showFossToast(
  context,
  const FossToast(
    variant: FossToastVariant.success,
    title: Text('Saved'),
  ),
);

Variants

variant sets the leading glyph and its tint. neutral (the default) has no glyph. info, success, warning, and error each show a colored status icon. loading shows a spinner and persists until you update or dismiss it.

showFossToast(
  context,
  const FossToast(
    variant: FossToastVariant.error,
    title: Text('Upload failed'),
    description: Text('Check your connection and try again.'),
  ),
);

Title and description

Both slots take any widget. The title sits on top; the description reads below it in a muted style.

showFossToast(
  context,
  const FossToast(
    title: Text('Invite sent'),
    description: Text('They will get an email shortly.'),
  ),
);

Action

action adds a trailing widget, typically a button that responds to the toast.

showFossToast(
  context,
  FossToast(
    title: const Text('Message archived'),
    action: FossButton(
      variant: FossButtonVariant.ghost,
      onPressed: undo,
      child: const Text('Undo'),
    ),
  ),
);

Duration

By default a toast clears after five seconds. Pass duration to change that; loading toasts ignore it and persist.

showFossToast(
  context,
  const FossToast(
    title: Text('Copied'),
    duration: Duration(seconds: 2),
  ),
);

Loading to result

showFossToast returns a FossToastHandle. Show a loading toast, run the work, then update the handle to its result. No BuildContext is threaded back.

final toast = showFossToast(
  context,
  const FossToast(variant: FossToastVariant.loading, title: Text('Saving...')),
);

await save();

toast.update(
  const FossToast(variant: FossToastVariant.success, title: Text('Saved')),
);

One-off styling

A single toast can override the resolved surface with a FossToastStyle. Every field is optional and falls back to the theme.

const FossToast(
  title: Text('Saved'),
  style: FossToastStyle(borderRadius: 8),
);

API

FossToaster

Hosts the toasts over its subtree. Mount one near the app root.

Prop	Type	Default	Description
`child`	`Widget`	required	The app subtree below the toasts.

showFossToast

FossToastHandle showFossToast(BuildContext context, FossToast toast) raises toast on the nearest FossToaster and returns a handle to it. It throws if no FossToaster is an ancestor.

FossToastHandle

A handle to a raised toast, returned by showFossToast, so the caller can update or dismiss it without a BuildContext.

Member	Type	Description
`update`	`void Function(FossToast)`	Replaces the message in place and restarts its timer.
`dismiss`	`void Function()`	Removes the toast now. A no-op once it has left the screen.

FossToast

Prop	Type	Default	Description
`title`	`Widget?`	`null`	The title line.
`description`	`Widget?`	`null`	The description below the title.
`variant`	`FossToastVariant`	`neutral`	The kind of toast.
`icon`	`Widget?`	`null`	Overrides the default leading glyph. Null hides the slot for `neutral`.
`action`	`Widget?`	`null`	An optional trailing action.
`duration`	`Duration?`	`null`	Overrides the auto-dismiss delay. Ignored for `loading`.
`style`	`FossToastStyle?`	`null`	Per-instance overrides on the theme.

FossToastController

Owns the queue of live toasts and their timers. A FossToaster creates and holds one; reach it with FossToastScope.of(context).

Member	Type	Description
`show`	`int Function(FossToast)`	Enqueues a toast and returns its id.
`update`	`void Function(int, FossToast)`	Replaces the message of an id in place and restarts its timer.
`dismiss`	`void Function(int)`	Removes an id.
`clear`	`void Function()`	Removes every toast.
`entries`	`List<FossToastEntry>`	The live toasts, oldest first.
`defaultDuration`	`static const Duration`	The default auto-dismiss delay (5000ms).
`maxVisible`	`static const int`	The most toasts shown at once (3).

FossToastScope

FossToastScope.of(context) returns the nearest FossToastController, throwing when no FossToaster is an ancestor.

FossToastStyle

Prop	Type	Default	Description
`backgroundColor`	`Color?`	`null`	Fill of the surface.
`borderColor`	`Color?`	`null`	Color of the 1px border.
`borderRadius`	`double?`	`null`	Corner radius in logical pixels.
`titleStyle`	`TextStyle?`	`null`	Style of the title, merged over the token default.
`descriptionStyle`	`TextStyle?`	`null`	Style of the description, merged over the token default.

FossToastVariant

neutral, loading, info, success, warning, error.

Live demo

Open the interactive gallery to try variants, title and description, and action with live knobs.

On this page