Hz Toast #

A highly customizable and feature-rich toast notification package for Flutter applications. Display beautiful, animated toast messages with various types, styles, and interactive features.

Demo #

Features #

• 🎨 Multiple Toast Types: Error, Success, Warning, and Info with predefined color schemes
• 🎭 Fully Customizable: Colors, icons, decorations, padding, margins, and more
• ⏱️ Auto-hide with Progress Bar: Optional progress bar showing remaining time
• 🔄 Dynamic Updates: Update toast content while it's displayed
• 📱 Responsive: Adapts to different screen sizes with configurable max width
• ✨ Smooth Animations: Beautiful slide and fade animations
• 🖱️ Interactive: Clickable toasts with custom tap handlers
• 🎯 Flexible Positioning: Support for all four corners (top-left, top-right, bottom-left, bottom-right)
• 🎛️ Builder Pattern: Custom builders for title, icons, and close buttons
• 🔧 Easy Integration: Simple overlay setup with minimal configuration

Getting Started #

Add this to your package's pubspec.yaml file:

dependencies:
  hz_toast: ^0.0.7

Then run:

flutter pub get

Setup #

Setting up Hz Toast is simple! Just add the HzToastInitializer widget to your MaterialApp's builder:

import 'package:flutter/material.dart';
import 'package:hz_toast/hz_toast.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Your App',
      theme: ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple)),
      home: const MyHomePage(),
      builder: (context, child) {
        // Add this widget to enable toasts
        return HzToastInitializer(child: child!);
      },
    );
  }
}

The HzToastInitializer widget creates its own overlay system, eliminating any "No Overlay widget found" errors. This approach is simple, reliable, and doesn't require complex setup.

How it works: The HzToastInitializer widget creates a built-in overlay to display toasts. When you call HzToast.show(), it automatically uses this overlay system. No manual initialization needed!

Alternative Manual Setup #

If you prefer explicit control over the overlay setup, you can still use the traditional approach:

MaterialApp(
  builder: (context, child) {
    return Material(
      child: Overlay(
        initialEntries: [
          OverlayEntry(builder: (context) => child!),
          OverlayEntry(builder: (context) => const HzToastWidget()),
        ],
      ),
    );
  },
)

Basic Usage #

Simple Toast #

// Show a success toast
HzToast.show(HzToastData(
  'Operation completed successfully!',
  type: HzToastType.success,
));

// Show an error toast
HzToast.show(HzToastData(
  'An error occurred!',
  type: HzToastType.error,
));

// Show a warning toast
HzToast.show(HzToastData(
  'This is a warning message!',
  type: HzToastType.warning,
));

// Show an info toast
HzToast.show(HzToastData(
  'Here\'s some information.',
  type: HzToastType.info,
));

Toast with Progress Bar #

HzToast.show(HzToastData(
  'Processing your request...',
  type: HzToastType.info,
  duration: const Duration(seconds: 5),
  showProgressBar: true,
));

Custom Styled Toast #

HzToast.show(HzToastData(
  'Custom styled toast!',
  backgroundColor: Colors.purple,
  textColor: Colors.yellow,
  iconColor: Colors.yellow,
  padding: const EdgeInsets.all(16),
  margin: const EdgeInsets.only(right: 8, bottom: 16),
  borderRadius: BorderRadius.circular(16),
  titleBuilder: (title, color) {
    return Text.rich(TextSpan(
      text: '🔥 ',
      children: [
        TextSpan(
          text: title,
          style: TextStyle(
            fontWeight: FontWeight.w700,
            color: color,
          ),
        ),
        const TextSpan(text: ' 🔥'),
      ],
    ));
  },
));

Toast Positioning #

Hz Toast supports positioning toasts in any corner of the screen using the alignment property:

// Top-right corner (default)
HzToast.show(HzToastData(
  'Top right toast',
  type: HzToastType.info,
  alignment: HzToastAlignment.topRight,
));

// Top-left corner
HzToast.show(HzToastData(
  'Top left toast',
  type: HzToastType.success,
  alignment: HzToastAlignment.topLeft,
));

// Bottom-right corner
HzToast.show(HzToastData(
  'Bottom right toast',
  type: HzToastType.warning,
  alignment: HzToastAlignment.bottomRight,
));

// Bottom-left corner
HzToast.show(HzToastData(
  'Bottom left toast',
  type: HzToastType.error,
  alignment: HzToastAlignment.bottomLeft,
));

The HzToastInitializer automatically handles all alignments - you only need to add one instance to your app's builder, and it will display toasts in the correct positions based on their alignment property.

Advanced Usage #

Dynamic Toast Updates #

You can update a toast's content while it's being displayed:

void showProgressToast() async {
  final id = UniqueKey().toString();
  ValueNotifier<int> progress = ValueNotifier<int>(0);

  final result = HzToast.show(HzToastData(
    'Processing...',
    id: id,
    type: HzToastType.info,
    autoHide: false,
    clickable: false,
    showCloseIcon: false,
    titleBuilder: (title, color) {
      return ValueListenableBuilder<int>(
        valueListenable: progress,
        builder: (context, value, child) {
          return Text(
            '$title (${value.toStringAsFixed(0)}%)',
            style: TextStyle(
              fontWeight: FontWeight.w500,
              color: color,
            ),
          );
        },
      );
    },
  ));

  if (result) {
    // Simulate progress
    for (int i = 1; i <= 100; i++) {
      await Future.delayed(const Duration(milliseconds: 80));
      progress.value = i;
    }

    // Update to completion state
    HzToast.update(id, HzToastData('Completed!', type: HzToastType.success));
    HzToast.hideIn(id, const Duration(seconds: 1));
  }

  progress.dispose();
}

Handling Toast Events #

HzToast.show(HzToastData(
  'Tap me!',
  type: HzToastType.info,
  clickable: true,
  onTap: () {
    print('Toast was tapped!');
    // Perform some action
  },
  onClose: () {
    print('Toast was closed!');
    // Cleanup or additional logic
  },
));

HzToastData Properties #

Styling Properties #

Builder Properties #

HzToast Methods #

Toast Types #

The package includes four predefined toast types with their own color schemes:

• HzToastType.error: Red color scheme for error messages
• HzToastType.success: Green color scheme for success messages
• HzToastType.warning: Orange color scheme for warnings
• HzToastType.info: Blue color scheme for informational messages

Each type automatically sets appropriate colors for icons, text, and close buttons, but these can be overridden with custom colors.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details. # hz_toast