jaspr_notifications #

A simple, convenient and customizable way to display in-app notifications for web projects built with the Jaspr framework.

Features #

• Easy to Use: A simple API to show, hide, and clear notifications globally.
• Pre-defined Types: Includes built-in styles for success, info, warning, and error notifications.
• Highly Customizable: Tailor the look and feel of notifications using custom styles, classes, and alignments.
• Flexible Positioning: Configure notifications to appear at any corner of the screen, or centered.
• Timed or Sticky: Notifications can automatically dismiss after a duration or be "sticky" until manually closed.
• Built-in Animations: Comes with smooth fade and slide animations for notifications entering and leaving the view.

try the live demo : demo

Installation #

Add the package to your pubspec.yaml file:

dart pub add jaspr_notifications

Usage #

Using jaspr_notifications is a simple two-step process.

1. Add the NotificationView #

add the NotificationView to your page. It's best to place it as close to the root of the page as possible to avoid interference from the rest of your app logic.

note that it must be a child of a hydrated component.

import 'package:jaspr/jaspr.dart';
import 'package:jaspr_notifications/jaspr_notifications.dart' as n;

@client // <-- this is required for the notifications to work
class Home extends StatefulComponent {
  const Home({super.key});

  @override
  State createState() => HomeState();
}

class HomeState extends State<Home> {
  @override
  Component build(BuildContext context) {
    return fragment([
      n.NotificationView(),

      // ... the rest of the page
    ]);
  }
}

The NotificationView will only render once. Any duplicates in the component treee will be ignored.

2. Show a Notification #

Once the NotificationView is in place, you can trigger notifications from anywhere in your application using the global showNotification() function.

import 'package:jaspr/jaspr.dart';
import 'package.jaspr_notifications/jaspr_notifications.dart' as n;

class MyButton extends StatelessComponent {
  const MyButton({super.key});
  @override
  Component build(BuildContext context) {
    return button(
      events: {
        'click': (event) {
          // Create a notification object
          final notification = n.Notification(
            title: 'Success!',
            message: 'Your profile has been updated.',
            type: NotificationType.success,
            duration: Duration(seconds: 3),
          );

          // Show it!
          n.showNotification(notification);
        },
      },
      [text('Update Profile')],
    );
  }
}

You can also use the convenient .show() method directly on a Notification instance:

Notification(
  title: 'Heads Up!',
  message: 'A new version is available.',
  type: NotificationType.info,
  duration: Duration(seconds: 5),
).show();

Customization #

You can customize notifications at both the global level (in the NotificationView) and the individual level (on the Notification object).

Customizing the NotificationView #

The NotificationView component offers several parameters to control the layout and default styling of all notifications.

NotificationView(
  // Align notifications to the top-left corner
  verticalAlignment: JustifyContent.start,
  horizontalAlignment: AlignItems.start,

  // Add some padding from the screen edges
  padding: Padding.all(2.rem),

  // Reverse the order so new notifications appear on top
  reverseOrder: true,

  // Apply default styles to all notification containers
  notificationStyles: Styles(
    radius: BorderRadius.circular(50.percent),
    shadow: BoxShadow(offsetX: 15.px, offsetY: 15.px, color: Colors.blue),
  ),

  // Apply default CSS classes to all notification containers (for tailwind users)
  notificationClasses: 'my-custom-notification',
)

you can also specify a custom notification builder function :

NotificationView(
    notificationBuilder: (notification, key)  => div(
        key: key,
        [text(notification.message)],
    )
)

Customizing Individual Notifications #

The Notification class has a rich set of properties to define its specific behavior and appearance, styles that are specified on the Notification object will override the default styles specified in the NotificationView component, classes specified this way also take precedence.

final myNotification = Notification(
  id: 'unique-id', // Optional: provide a unique ID
  title: 'Custom Notification',
  message: 'This one has custom styling and behavior.',
  type: NotificationType.custom, // Use .custom to disable default icons/colors
  
  // This notification will not auto-dismiss
  sticky: true,

  // Wait 1 second before showing the notification
  delay: Duration(seconds: 1),

  // Apply specific CSS classes
  classes: 'dark-theme special-border',
  
  // Override any styles with a Styles object
  styles: Styles(color: Colors.white),

  // Add an onClick handler for this notification
  onClick: () {
    print('Notification clicked!');
    // The default behavior is to dismiss, but you can override it.
  },
);

myNotification.show();

API Reference #

The package exposes three main global functions to control notifications:

• void showNotification(Notification notification) Displays the given notification.

• void removeNotification(String id) Removes a specific notification from view by its ID. Useful for sticky notifications.

• void clearNotifications() Removes all currently visible notifications.

Roadmap #

• ❌ buttons for actions
• ❌ integration for browser notifications
• ❌ smooth shift animations for already displayed notifications

Contributing #

Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitLab.