pub.dev

adaptive_palette

3.1.0HardikSJain/adaptive_palette ↗New releases in your daily digest, changelog included.

Immersive fluid animated backgrounds from images. Weighted k-means color extraction, LRU cache, dark/light/auto fallback, and smooth orbital motion.

Last release 7 months ago
03 Mar 2026
Ships fairly regularly
a new release about every 3 weeks
Most releases are documented
notes for 12 of 14 stable releases
Nothing withdrawn
no release was ever pulled
11 months old
14 releases · first in 2025

Release timeline

14 releases since 2025

20252026

One column per month.

Releases

3.1.03 Mar 2026
FluidFallbackMode enum (dark / light / auto) on FluidBackground — defaults to auto (matches theme brightness)
Added

FluidFallbackMode enum (dark / light / auto) on FluidBackground — defaults to auto (matches theme brightness)

FluidPalette.fallbackLight() — pastel light-mode fallback palette

FluidPaletteExtractor.extractColors(ImageProvider, {int count}) — new primary extraction API; returns ranked List<Color>

FluidPaletteExtractor.warmup(List<ImageProvider>) — parallel cache pre-warm

FluidPaletteCache — LRU singleton (30 entries, SHA-1 keyed); auto-populated on every extraction

Changed

FluidBackground.animate default → false (battery-friendly; opt-in with animate: true)

Animation toggle is now smooth — resumes from frozen phase instead of jumping

Fixed

Stale async race in FluidBackground: rapid image provider changes no longer corrupt the displayed palette

Deprecated

FluidPaletteExtractor.extract(ui.Image) — use extractColors(ImageProvider) instead; will be removed in v4.0.0
Open source →
3.0.024 Dec 2025Deprecated

All v2.x APIs are deprecated and will be removed in v4.0.0.

Major Release - Complete Redesign

This release completely redesigns the package around a single, powerful concept: FluidBackground. The focus is now exclusively on creating immersive, fluid animated backgrounds inspired by modern music apps.

All v2.x APIs are deprecated and will be removed in v4.0.0.

New Philosophy

The package now provides two simple APIs:

FluidBackground Widget - Drop-in animated background (recommended)
FluidPaletteExtractor - Manual color extraction for custom implementations

Old Material Design theming APIs (AdaptivePalette, PaletteScope, ThemeColors, etc.) are deprecated in favor of this simpler, more focused approach.

Added

FluidBackground Widget: One-line immersive animated backgrounds
- Optional image (null = matte fallback only)
- Instant matte gradient display (0ms startup)
- Smooth cross-fade transitions (1400ms)
- 4 layered ImageShaders with orbital motion
- Heavy 80σ Gaussian blur for atmosphere
- Corner radial glows (4 accents)
- Configurable parameters (blur, overlay, animation)
FluidPaletteExtractor API: Advanced color extraction
- Weighted k-means clustering (k=6, 10 iterations)
- Smart sampling (every 10th pixel, filters extremes)
- Vibrancy weighting: (sat × 0.75 + light × 0.25)
- Center proximity boost: 1.0 + 0.8 × decay
- Perceptual scoring: (vivid × 1.2 + mid × 0.8)
- Matte treatment (14% gray blend for whites)
- Dark base enforcement (≤ 0.22 lightness)
FluidPalette Model: Simple 5-color palette
- baseDark (guaranteed dark)
- accent1-4 (corner glows)
- lerp() for animations
- copyWith() for immutability

Deprecated

All of these will be removed in v4.0.0:

❌ AdaptivePalette.fromImage() → Use FluidPaletteExtractor.extract()
❌ PaletteScope → Use FluidBackground widget
❌ ThemeColors → Use FluidPalette
❌ AdaptiveImageOverlay → Use FluidBackground
❌ AdaptiveGlowImageFrame → Use FluidBackground
❌ AdaptiveGradientScaffold → Use FluidBackground
❌ ExtractionConfig → No longer needed
❌ ExtractionQuality → No longer needed

Migration Guide

Before (v2.x):

final colors = await AdaptivePalette.fromImage(NetworkImage(url));
MaterialApp(theme: colors.toThemeData());

After (v3.0):

FluidBackground(
  imageProvider: NetworkImage(url),
  child: YourContent(),
)

Or for manual extraction:

final image = await loadImageFromProvider(NetworkImage(url));
final palette = await FluidPaletteExtractor.extract(image);

Changed

README - Completely rewritten to focus on FluidBackground
Library docs - Simplified to showcase two main APIs
Package description - Now emphasizes fluid backgrounds
Export order - Primary APIs first, deprecated APIs last

Why the Change?

The v2.x APIs were complex and trying to solve too many problems:

Material Design theming
WCAG accessibility
Multiple widget variants
Theme animation systems

v3.0 simplifies everything:

One goal: Beautiful fluid backgrounds
Two APIs: Widget (easy) or Extractor (custom)
Zero complexity: No configs, no quality presets, no theme systems

Backward Compatibility

All v2.x code continues to work with deprecation warnings. You have until v4.0 to migrate.

Breaking Changes

None - all v2.x APIs still work (deprecated but functional).

Open source →

2.0.321 Dec 2025

README image now uses GitHub raw URL for proper display on pub.dev

Fixed

README image now uses GitHub raw URL for proper display on pub.dev

Open source →

2.0.221 Dec 2025

Package preview image (adaptive_palette.png) showing the library in action

Added

Package preview image (adaptive_palette.png) showing the library in action

Changed

Updated README installation instructions to reference correct version

Open source →

2.0.11 Dec 20252 sources agree

Critical Fix : Added missing dart:ui import in theme.dart for Brightness enum

Fixed

Critical Fix: Added missing dart:ui import in theme.dart for Brightness enum
Package now compiles correctly when used as a dependency

Open source →

2.0.01 Dec 2025

Major Release - Architectural Rewrite

This release restructures the package with improved modularity, performance, and developer experience. The core API remains backward compatible - most v1.x code continues to work without changes.

Added

Quality Presets: ExtractionQuality.fast, balanced, and high for different use cases
ExtractionConfig: Unified configuration object with quality presets and callbacks
Performance Monitoring: ExtractionStats with duration, cache hits, and image type detection
Cache Management: Configurable size (default: 32), warmup API, and statistics
Debug Callbacks: onDebug and onError for real-time insights
Diversity Control: Configurable weight (0.0-2.0) to prevent selecting similar colors
Comprehensive Tests: 59 unit tests covering all core algorithms
Extensive Documentation: 15+ usage examples and migration guide

Changed

Modular Architecture: Refactored from 1636-line monolithic file into 12 clean modules
Improved WCAG Compliance: More reliable contrast ratio calculations
Better Default Parameters: Optimized for real-world performance
Enhanced Theme Generation: Fixed color contrast bugs, improved fallback behavior
Larger Cache: Increased from 16 to 32 entries by default

Performance

Typical extraction times (MacBook Pro M1, Release mode):

Quality	Time	Use Case
Fast	30-50ms	Lists, thumbnails
Balanced	60-90ms	General use (default)
High	90-140ms	Hero images
Cache Hit	<1ms	All cached images

Open source →

Additional notes

Major Release - Architectural Rewrite

This release restructures the package with improved modularity, performance, and developer experience. The core API remains backward compatible - most v1.x code continues to work without changes.

Added

Quality Presets: ExtractionQuality.fast, balanced, and high for different use cases
ExtractionConfig: Unified configuration object with quality presets and callbacks
Performance Monitoring: ExtractionStats with duration, cache hits, and image type detection
Cache Management: Configurable size (default: 32), warmup API, and statistics
Debug Callbacks: onDebug and onError for real-time insights
Diversity Control: Configurable weight (0.0-2.0) to prevent selecting similar colors
Comprehensive Tests: 59 unit tests covering all core algorithms
Extensive Documentation: 15+ usage examples and migration guide

Changed

Modular Architecture: Refactored from 1636-line monolithic file into 12 clean modules
Improved WCAG Compliance: More reliable contrast ratio calculations
Better Default Parameters: Optimized for real-world performance
Enhanced Theme Generation: Fixed color contrast bugs, improved fallback behavior
Larger Cache: Increased from 16 to 32 entries by default

Breaking Changes

Widget Parameters: Now use ExtractionConfig instead of individual parameters

// Before
AdaptiveImageOverlay.network(url, resize: 96, quantizeColors: 24)

// After
AdaptiveImageOverlay.network(url, config: ExtractionConfig.fromQuality(ExtractionQuality.high))

ThemeColors.toThemeData(): Changed from static to instance method

// Before
ThemeColors.toThemeData(colors, brightness: Brightness.dark)

// After
colors.toThemeData(brightness: Brightness.dark)

Internal Imports: Don't import from lib/src/ - use public API only

Backward Compatible

The following v1.x code works without changes:

AdaptivePalette.fromImage() with named parameters
PaletteScope widget and controller
All ThemeColors properties and copyWith()

See MIGRATING.md for detailed upgrade instructions.

Fixed

WCAG contrast calculation bugs in theme generation
Type safety issues (34 analyzer warnings → 0)
Memory leaks in cache management
Documentation accuracy

Performance

Typical extraction times (MacBook Pro M1, Release mode):

Quality	Time	Use Case
Fast	30-50ms	Lists, thumbnails
Balanced	60-90ms	General use (default)
High	90-140ms	Hero images
Cache Hit	<1ms	All cached images

1.0.718 Nov 2025

Version 1.0.7: Adaptive color detection

Open source →

Additional notes

Changed

Major algorithm improvement with adaptive scoring for different image types
Increased default quantizeColors to 32 and resize to 128
Now uses CAM16 perceptual color space for better accuracy

Improved

Adaptive thresholds for colorful, monochromatic, and normal images
Better color diversity through hue distance calculations
Smart filtering prevents selecting multiple shades of same color

Open source →

1.0.618 Nov 2025

Critical compatibility fix: replaced toARGB32() with .value for Flutter 3.0+

Fixed

Critical compatibility fix: replaced toARGB32() with .value for Flutter 3.0+

Open source →

1.0.518 Nov 2025

Universal compatibility using bit operations for color component extraction

Fixed

Universal compatibility using bit operations for color component extraction

Open source →

1.0.415 Nov 2025

Lowered minimum SDK to >=3.0.0 <4.0.0 (Flutter 3.0+ support)

Changed

Lowered minimum SDK to >=3.0.0 <4.0.0 (Flutter 3.0+ support)

Open source →

1.0.314 Nov 2025

Upgraded flutter_lints from ^5.0.0 to ^6.0.0 for latest linting rules

Changed

Upgraded flutter_lints from ^5.0.0 to ^6.0.0 for latest linting rules
Cleaned up pubspec.yaml by removing unnecessary comments
Improved code formatting and consistency across library files
Updated README installation instructions to reference version 1.0.3

Fixed

Minor code formatting improvements for better readability
Consistent code style throughout the package

Open source →

1.0.212 Nov 2025

Nothing published for this version

1.0.111 Nov 2025

Nothing published for this version

1.0.011 Nov 2025

Initial release of Adaptive Palette

Added

Initial release of Adaptive Palette
Automatic color palette extraction from images using CAM16/HCT color space
WCAG AA/AAA contrast compliance for all generated themes
Smooth theme animations with PaletteScope
High-performance median-cut quantization algorithm
Smart LRU caching with content-based keys
AdaptiveBlurredBackground widget (Luma/Spotify-style)
AdaptiveBlurredBackgroundWithImage widget variant
Dark and light theme support
Material Design 3 integration
Comprehensive inline documentation
Example app with image gallery

Features

Extract vibrant, muted, or dominant color strategies
Configurable blur, scale, and overlay effects
Cross-fade transitions between themes
Hero animations for smooth page transitions
Responsive image loading with error handling
Accessibility-first design principles

Performance

~50-150ms palette extraction time
<1ms cache hit latency
60 FPS smooth animations
Memory-efficient downsampling

Open source →

Additional notes

Added

Initial release with CAM16/HCT color extraction
WCAG AA/AAA contrast compliance
PaletteScope for animated theme transitions
Three pre-built widgets
Material Design 3 integration

Open source →

Your coding agent can read these notes before it upgrades. Set up the MCP server →