snacko 1.0.1

A lightweight, customizable, and modern Flutter snackbar package for building beautiful in-app notifications with smooth animations, flexible styling, and easy integration.

Snacko 🍿

A lightweight, customizable, and modern Flutter snackbar package. Build beautiful in-app notifications with smooth animations, glassmorphism effects, and native-feeling interactions.

---

✨ Features

• 🚀 Overlay Authority: Uses Flutter's Overlay system to stay visible over Dialogs, Bottom Sheets, and full-screen modals.
• 🎨 Modern Aesthetics: Built-in Glassmorphism (blur) effects and vibrant, curated color palettes.
• 🖐️ Interactive: Swipe-to-dismiss support and support for custom action buttons.
• 📱 Adaptive: Automatically respects Safe Areas (notches/home indicators) and provides OS-specific default positions (Top for iOS, Bottom for Android).
• 💓 Tactile Feedback: Integrated haptic feedback for a premium native feel.
• ⏳ Progress Tracking: Subtle animated progress bar showing remaining duration.
• ⚡ Spring Physics: Organic, elastic animations for smooth entry and exit.

---

📦 Installation

Add snacko to your pubspec.yaml:

dependencies:
  snacko: ^0.0.1

Or run:

flutter pub add snacko

---

🚀 Setup & Quick Start

You can use Snacko in two ways: With Context or Without Context (Global Setup).

Option 1: Without Context (Recommended)

By setting up a GlobalKey<NavigatorState>, you can trigger Snacko from anywhere in your app (like Blocs, Services, or Repositories) without needing to pass BuildContext around.

1. Setup in main.dart:

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

void main() {
  runApp(MyApp());
}

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

  // Create a global navigator key
  final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

  @override
  Widget build(BuildContext context) {
    // Initialize Snacko
    Snacko.init(navigatorKey);

    return MaterialApp(
      navigatorKey: navigatorKey, // Important: pass it to your MaterialApp
      title: 'Snacko Demo',
      home: const HomeScreen(),
    );
  }
}

2. Use anywhere:

Snacko.show(
  message: 'Profile updated successfully!',
  type: SnackType.success,
);

Option 2: With Context

If you prefer not to use a global key, or you only need to show notifications from within UI components, you can pass the BuildContext directly:

Snacko.show(
  context: context,
  message: 'Profile updated successfully!',
  type: SnackType.success,
);

---

🛠️ Detailed Usage & Use Cases

1. Success Notification (with Title)

Perfect for confirming user actions like form submissions or settings updates.

Snacko.show(
  title: 'Success!',
  message: 'Your payment was processed securely.',
  type: SnackType.success,
);

2. Error Alert (with Action)

Use this for critical failures where the user might need to retry or see details.

Snacko.show(
  title: 'Upload Failed',
  message: 'Could not connect to the server.',
  type: SnackType.error,
  actionLabel: 'RETRY',
  onAction: () {
    // Your retry logic here
  },
);

3. Informational Update (Custom Duration)

Great for non-critical background updates or new feature announcements.

Snacko.show(
  message: 'Syncing your library in the background...',
  type: SnackType.info,
  duration: 6000, // Display for 6 seconds
);

4. Warning (Custom Position)

Use for temporary warnings like low battery or session expiry.

Snacko.show(
  message: 'Your session will expire in 5 minutes.',
  type: SnackType.warning,
  position: SnackPosition.top, // Force top position
);

---

📖 API Reference

Snacko.init(GlobalKey<NavigatorState> key)

Initializes the global navigator key. Required if you want to use Snacko.show without passing a context.

Snacko.show(...)

Parameter	Type	Default	Description
context	BuildContext?	null	Optional. Used to find the app's Overlay. If not provided, Snacko.init must have been called.
message	String	Required	The main notification text.
title	String?	null	Optional bold header text.
type	SnackType	SnackType.info	Visual style: success, error, warning, info.
position	SnackPosition?	Adaptive	top or bottom. Defaults to OS-specific best practice.
duration	int	4000	Display duration in milliseconds.
actionLabel	String?	null	Text for an optional action button.
onAction	VoidCallback?	null	Callback function when action button is pressed.

---

🛡️ Why Snacko?

Traditional SnackBars in Flutter are tied to a Scaffold. This means they:

1. Get hidden behind Dialogs or Bottom Sheets.
2. Require a Scaffold even if your screen doesn't have one.
3. Often look outdated without significant custom styling.
4. Require plumbing BuildContext to business logic.

Snacko solves this by living in the Overlay. It is independent of the Scaffold and remains visible until dismissed, regardless of navigation changes or multi-layered UI, and optionally removes the BuildContext requirement.

---

🤝 Contributing

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

📄 License

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