Fluid Progress Indicator #

Beautiful fluid progress indicators for Flutter with customizable wave animations, gradients, rounded corners, and smooth fill transitions. Accessible and performant.

Demo #

Screenshot #

Video Demo #

Getting Started with testing #

1. Run flutter pub get to install the necessary dependencies
2. Run flutter test to execute all tests

Table of contents #

• Highlights / Features
• Platform support & Requirements
• Getting started
• Setup (Android, iOS, Web, macOS, Windows, Linux)
• Usage
• Configuration
  • Background configuration
• Theming & accessibility
• Advanced
• Examples
• API description
• Limitations
• Performance
• FAQ / Troubleshooting
• Roadmap
• Contributing
• User privacy notes
• Author, Maintainers & Acknowledgements
• License

Highlights / Features #

• 💧 Fluid / liquid fill animation with configurable wave count & amplitude
• 🎛️ Customizable: colors, gradients, borders (via background), rounded corners, text/child overlay
• ♿ Accessible: supports semantics labels and value announcements
• ⚡ Efficient: single CustomPainter, cache‑friendly; no custom shaders required
• 🧩 Composable: use anywhere a Widget is accepted; works with Bloc, Riverpod, or vanilla setState
• 🎨 Theming: plays nicely with Material 3 (ThemeData.colorScheme) and dark mode

Folder structure (suggested)

fluid_progress_indicator/
├─ lib/
│  ├─ fluid_progress_indicator.dart
│  └─ src/
│     ├─ widgets/
│     ├─ painter/
│     └─ controller/
├─ example/
│  └─ lib/
│     └─ main.dart
├─ docs/
│  └─ images/
│     ├─ demo_light.gif
│     └─ demo_dark.gif
├─ test/
├─ analysis_options.yaml
├─ CHANGELOG.md
├─ CONTRIBUTING.md
├─ LICENSE
├─ README.md
└─ pubspec.yaml

Platform support & Requirements #

Requirements

• Flutter ≥ 3.19.0
• Dart ≥ 3.3.0 < 4.0.0
• iOS ≥ 12.0, macOS ≥ 10.14
• Android toolchain: Java 17, Kotlin 2.2.0, AGP ≥ 8.12.1, Gradle wrapper ≥ 8.13

Permissions

• INTERNET (only if you load network images in IndicatorBackgroundConfig.image).
• No other permissions required.

Getting started #

Quick Start #

Install the package:

flutter pub add fluid_progress_indicator

Or add it manually to your pubspec.yaml:

dependencies:
  fluid_progress_indicator: ^0.0.1

Then run:

flutter pub get

Import and use:

import 'package:fluid_progress_indicator/fluid_progress_indicator.dart';

FluidProgressIndicator(
  maxProgress: 100,
  progress: 75,
  fillColor: Colors.blue,
)

Setup (Android, iOS, Web, macOS, Windows, Linux) #

No special/native setup is required.For Web, best visual quality with:

flutter run -d chrome --web-renderer canvaskit

Usage #

Minimal

FluidProgressIndicator(
  maxProgress: 100,
  progress: 62,          // current value (0..maxProgress)
  fillColor: Colors.blue // OR use fillGradient
)

With gradient, background, and overlay text

FluidProgressIndicator(
  maxProgress: 100,
  progress: 67,
  backgroundConfig: const IndicatorBackgroundConfig(
    gradient: LinearGradient(
      colors: [Colors.lightBlueAccent, Colors.blueAccent],
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
    ),
  ),
  fillGradient: const LinearGradient(
    colors: [Color(0xFF64B5F6), Color(0xFF1976D2)],
    begin: Alignment.bottomCenter,
    end: Alignment.topCenter,
  ),
  // Animated overlay (normalized value 0.0..1.0)
  animationChildBuilder: (context, value) => Text(
    '${(value * 67).toInt()} %',
    style: Theme.of(context).textTheme.headlineSmall?.copyWith(color: Colors.white),
  ),
)

With rounded corners, progress animation, and a nested CircularProgressIndicator

FluidProgressIndicator(
  maxProgress: 100,
  progress: 100,
  borderRadius: 24,
  backgroundConfig: IndicatorBackgroundConfig(
    color: Theme.of(context).colorScheme.onSurface,
  ),
  fillColor: Theme.of(context).colorScheme.primaryContainer,
  animationChildBuilder: (context, value) => Stack(
    alignment: Alignment.center,
    children: [
      SizedBox(
        width: 72, height: 72,
        child: CircularProgressIndicator(
          value: value,                // 0.0..1.0 normalized
          color: Colors.red,
          strokeWidth: 8,
        ),
      ),
      Text(
        '${(value * 100).toInt()} %',
        style: Theme.of(context).textTheme.titleMedium?.copyWith(color: Colors.red),
      ),
    ],
  ),
)

Indefinite background with image & animated fill

const FluidProgressIndicator(
  maxProgress: 0,
  progress: 0,
  backgroundConfig: IndicatorBackgroundConfig(
    image: DecorationImage(
      image: AssetImage('assets/bg-image.png'),
      fit: BoxFit.cover,
    ),
  ),
  fillColor: Color(0xFF29ED74),
)

✅ The animationChildBuilder callback receives a normalized value 0.0..1.0 so your label can animate smoothly while the fluid fills.

Configuration #

Important: At least one of fillColor or fillGradient must be non‑null.

Background configuration #

IndicatorBackgroundConfig lets you style the container behind the fluid:

IndicatorBackgroundConfig(
  color: Colors.black12,
  gradient: const LinearGradient(colors: [Colors.teal, Colors.tealAccent]),
  image: const DecorationImage(
    image: AssetImage('assets/bg-image.png'),
    fit: BoxFit.cover,
  ),
  border: Border.all(color: Colors.white24, width: 1.5),
)

Theming & accessibility #

• Respects ThemeData(useMaterial3: true) and color schemes out of the box.
• You can pass high‑contrast fills and clear text colors for readability.
• Add semantics around the widget if you need spoken progress updates:

Semantics( label: 'Upload progress', value: '${(normalized * 100).toStringAsFixed(0)} percent', child: FluidProgressIndicator(...), )

Advanced #

• Wave detail: Tune noOfWaves and waveAmplitude for the desired look.
• Animation: heightAnimationDuration controls how quickly the fill height catches up when progress changes.
• Overlay animation: animationChildBuilder gets a normalized value in 0.0..1.0 to animate text/indicators in sync.

Examples #

A runnable example is provided in example/ (the snippet below is the actual main.dart included in your package):

MaterialApp( theme: ThemeData(useMaterial3: true), home: const MyHomePage(), ); Run:

flutter run example/lib/main.dart

Common Use Cases #

• 📥 Download/upload progress
• ⏱️ Timer visualization
• 🎯 Goal tracking (fitness, savings, etc.)
• 🔋 Battery level indicators
• 💾 Storage usage displays

Running Tests #

• To run all tests, use the command flutter test
• To run a specific test file, use the command flutter test <path/to/test_file.dart>
• To run a specific test within a file, use the command flutter test <path/to/test_file.dart> --name=testName

API description #

Public entrypoint

import 'package:fluid_progress_indicator/fluid_progress_indicator.dart';

FluidProgressIndicator(
  maxProgress: 100,
  progress: 67,
  backgroundConfig: const IndicatorBackgroundConfig(...),
  fillColor: Colors.blue,                  // or fillGradient
  noOfWaves: 1,
  waveAmplitude: 4.0,
  borderRadius: 24,
  heightAnimationDuration: const Duration(milliseconds: 2000),
  animationChildBuilder: (ctx, normalized) => Text('${(normalized * 100).toInt()}%'),
);
Background config

const IndicatorBackgroundConfig({
  this.color,
  this.gradient,
  this.image,
  this.border,
});

Limitations #

• The widget does not fetch progress; you supply progress updates (e.g., from a download/upload).
• Excessively large sizes combined with high wave counts may reduce performance on very low‑end devices.
• For Web, CanvasKit renderer is recommended for best fidelity.

Performance #

• Single CustomPainter pipeline; minimal layout churn.
• Avoid rebuilding with every tick if progress has not changed.
• In lists, consider wrapping items in RepaintBoundary.
• Keep noOfWaves and waveAmplitude reasonable for ultra‑low‑end devices.

FAQ / Troubleshooting #

Q: My overlay text looks slightly blurry.
A: Use whole‑pixel font sizes, and wrap the indicator in a RepaintBoundary when used in lists.

Q: Web performance dips with big indicators.
A: Use --web-renderer canvaskit, reduce noOfWaves, and lower waveAmplitude.

Q: How do I animate the label from 0 to progress?
A: Use animationChildBuilder; the normalized parameter is 0.0..1.0 and tracks the fill animation.

Roadmap #

• Built‑in reduced‑motion preset
• Preset themes (success / warning / error)
• Multi‑segment / stacked fluid
• Directional waves (RTL/LTR)

Contributing #

Contributions welcome! Please read:

• CONTRIBUTING.md – setup, branch strategy, commit convention
• CODE_OF_CONDUCT.md

dart format . --set-exit-if-changed flutter analyze flutter test --coverage

User privacy notes #

This package does not collect or share any personal or sensitive user data.If you load network images for the background, your app will use the network as per your code; the package itself has no tracking.

Author, Maintainers & Acknowledgements #

• Developed by Rishabh Software.
• Thanks to the Flutter community for the amazing packages used in this project.

License #

This package is licensed under the MIT License. See LICENSE for details.

Made by RSPL Team #

Github • Website