Feedback

Toast

Short notifications stacked in a corner of the screen by JxToastRegion. You own the queue: add a toast to your state, remove it on dismiss or after a delay.

JxToast import 'package:jx_cli/ui.dart' New in 0.0.3

Preview

When to use it

  • Confirming an action that does not change the page ("Link copied").
  • An error from a background task.
  • An "Undo" right after a deletion.

States

Link copied to the clipboard.

Neutral
With an action

Minimal example

Dart
JxToastRegion([
  for (final message in messages) JxToast(message, tone: JxTone.success),
])

Complete example

A full Jaspr component you can paste into a project.

Dart
import 'dart:async';

import 'package:jaspr/jaspr.dart';
import 'package:jx_cli/ui.dart';

/// A toast queue: every toast leaves after five seconds or on dismiss.
@client
class Notifications extends StatefulComponent {
  const Notifications({super.key});

  @override
  State<Notifications> createState() => _NotificationsState();
}

class _NotificationsState extends State<Notifications> {
  final toasts = <(int, String)>[];
  int next = 0;

  void show(String message) {
    final id = next++;
    setState(() => toasts.add((id, message)));
    Timer(const Duration(seconds: 5), () => dismiss(id));
  }

  void dismiss(int id) => setState(() => toasts.removeWhere((t) => t.$1 == id));

  @override
  Component build(BuildContext context) {
    return Component.fragment([
      JxButton(onClick: () => show('Link copied.'), [.text('Copy the link')]),
      // Rendered from the start, even empty, so new toasts are announced.
      JxToastRegion([
        for (final (id, message) in toasts)
          JxToast(message, key: ValueKey(id), tone: JxTone.success, onDismiss: () => dismiss(id)),
      ]),
    ]);
  }
}

Properties

Property Type Default Description
message String required Text of the toast.
title String? null Bold first line.
tone JxTone neutral Color of the left border; warning and danger are announced at once.
action Component? null Usually a small JxButton , such as "Undo".
dismissLabel String 'Dismiss' Accessible name of the close button.
classes String? null Extra JX classes, appended after the component classes.

Related types

Name Role
JxToastRegion(toasts, position:, label:) The fixed corner where toasts stack: a <section> named "Notifications".
JxToastPosition bottomEnd, bottomStart, topEnd, topStart.

Events

Callback Type Fires when
onDismiss VoidCallback? The close button is pressed. Without it, no close button is shown.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.
  • Move the stack with position, or with classes on the region.

Responsive

  • The stack is min(24rem, 100% - 2rem) wide: on phones it spans the screen with a margin.

Accessibility

  • Each toast is role="status", or role="alert" for warning and danger.
  • Render the region when the page loads, even empty: live regions are only announced when they already exist.
  • Leave toasts on screen long enough to be read (five seconds or more), and never put the only way to do something in a toast.
  • The slide-up is disabled when the system asks for reduced motion.

Limitations

  • No built-in timer or queue: timing is up to you, as in the example.
  • Toasts do not pause when hovered.