fast_thumbhash library

Ultra-fast ThumbHash encoder/decoder for Dart and Flutter.

ThumbHash is a very compact representation of an image placeholder. It encodes the image's average color and a low-resolution version into a small byte array (typically 25-35 bytes).

Features

  • Ultra-fast decoding - 7x faster than naive implementation
  • Fast PNG encoding - 1.6x faster with pre-allocated buffers
  • Full alpha support - Images with transparency work correctly
  • Natural loading transitions - Smooth fade, blur, and scale effects
  • Zero dependencies - Pure Dart implementation

Quick Start

import 'package:fast_thumbhash/fast_thumbhash.dart';

// Create from base64 string
final hash = ThumbHash.fromBase64('3OcRJYB4d3h/iIeHeEh3eIhw+j3A');

// Use in Flutter Image widget
Image(image: hash.toImage())

// Get average color for background
final color = hash.toAverageColor();

Natural Image Loading

Use ThumbHashPlaceholder for automatic placeholder-to-image transitions:

ThumbHashPlaceholder(
  thumbHash: ThumbHash.fromBase64('3OcRJYB...'),
  image: NetworkImage('https://example.com/photo.jpg'),
  transition: TransitionConfig.blur,
)

Core Functions

For lower-level access, use these functions directly:

Performance

Benchmarked on typical hardware:

  • Decode: ~45μs per image
  • PNG encode: ~40μs per image
  • Total pipeline: ~85μs per image

Based on the original ThumbHash algorithm by Evan Wallace. See: https://github.com/evanw/thumbhash

Classes

ThumbHash
A Flutter-friendly wrapper for ThumbHash operations.
ThumbHashColor
Represents an RGBA color with values in range 0.0 to 1.0.
ThumbHashImage
Represents a decoded ThumbHash image with RGBA pixel data.
ThumbHashImageBuilder
A builder widget for creating custom ThumbHash loading experiences.
ThumbHashLoadingState
The current state of image loading, exposed to ThumbHashImageBuilder.
ThumbHashPlaceholder
A widget that displays a ThumbHash placeholder and transitions to the loaded image with a natural animation effect.
TransitionConfig
Configuration for transition animations.

Enums

ThumbHashTransition
Transition types for image loading animations.

Functions

rgbaToThumbHash(int w, int h, Uint8List rgba) → Uint8List
Encodes an RGBA image to a ThumbHash.
rgbaToThumbHashAsync(int w, int h, Uint8List rgba) → Future<Uint8List>
Encodes an RGBA image to a ThumbHash asynchronously.
thumbHashImageToPng(ThumbHashImage image) → Uint8List
Encodes a ThumbHash image to PNG format.
thumbHashImageToPngAsync(ThumbHashImage image) → Future<Uint8List>
Encodes a ThumbHash image to PNG format asynchronously.
thumbHashToApproximateAspectRatio(Uint8List hash) → double
Extracts the approximate aspect ratio of the original image.
thumbHashToAverageRGBA(Uint8List hash) → ThumbHashColor
Extracts the average color from a ThumbHash.
thumbHashToRGBA(Uint8List hash) → ThumbHashImage
Ultra-fast ThumbHash encoder/decoder.
thumbHashToRGBAAsync(Uint8List hash) → Future<ThumbHashImage>
Decodes a ThumbHash to an RGBA image asynchronously.

Typedefs

ImageErrorWidgetBuilder = Widget Function(BuildContext context, Object error, StackTrace? stackTrace)
Signature for a function that builds a widget when an image fails to load.
ThumbHashWidgetBuilder = Widget Function(BuildContext context, ThumbHashLoadingState state)
Signature for the builder function used by ThumbHashImageBuilder.