dither_animals

Cute animated dithered (stipple, halftone, and ordered-dither) animal widgets for Flutter.

_{🎬 Click the preview above or watch full HD video (animal_details.mp4)}

Rendered entirely on the Flutter Canvas using an ordered 8×8 Bayer dithering matrix, each animal features its own handcrafted animation curves, unique entrance/reveal transitions, facial expressions, idle breathing/swaying, and interactive poke physics with haptic feedback.

✨ Features

🐾 30 Handcrafted Chibi Animals & Elements: From owls, cats, and frogs to clouds, rockets, and cupcakes.
🎨 Ordered Bayer 8×8 Matrix Dithering: Authentic retro stipple rendering with smooth multi-layer density shading.
🕹️ Interactive Poke Shockwaves: Tap any animal to send an interactive radial wave ripple through the stipple grid, accompanied by haptic click feedback.
🔲 Multiple Dot Styles: Choose between crisp retro DitherDot.square pixels or organic halftone DitherDot.round circles.
🔄 Motion Modes: Seamless infinite animations (DitherMotion.loop) or one-time build entrances (DitherMotion.once).
🖼️ Custom Image Dithering: Pass any Flutter ImageProvider to dither and animate custom logos, avatars, or artwork.
⚡ Lightweight & High Performance: Vector paths sampled and dithered with hardware acceleration.

📦 Installation

Add dither_animals to your pubspec.yaml dependencies:

dependencies:
  dither_animals: ^1.0.0

Or run:

flutter pub add dither_animals

Then import the package in your Dart code:

import 'package:dither_animals/dither_animals.dart';

🚀 Quick Start

Display an animated owl with default settings:

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

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

  @override
  Widget build(BuildContext context) {
    return const Center(
      child: SizedBox(
        width: 140,
        height: 140,
        child: DitherAnimal(
          animal: DitherAnimalType.owl,
          color: Color(0xFFFF5A1F),
        ),
      ),
    );
  }
}

🦁 Built-in Animal Presets (30 Total)

Animal	Enum	Personality & Motion
🦉 Owl	`DitherAnimalType.owl`	Radial bloom, sways gently & blinks big round eyes
🐘 Elephant	`DitherAnimalType.elephant`	Left-to-right sweep, swings trunk & flaps ears
🐰 Rabbit	`DitherAnimalType.rabbit`	Bottom-up bounce, hops with twitching ears
🐟 Fish	`DitherAnimalType.fish`	Right-to-left glide, undulating tail & blows bubbles
🐢 Turtle	`DitherAnimalType.turtle`	Calm spiral reveal, paddles flippers smoothly
🐱 Cat	`DitherAnimalType.cat`	Diagonal leap, playful tail swish & perked ears
🐧 Penguin	`DitherAnimalType.penguin`	Bottom-up waddle, cute side-to-side shuffle
🐸 Frog	`DitherAnimalType.frog`	Springy bottom bounce, big vertical hops
🐙 Octopus	`DitherAnimalType.octopus`	Top-down drop, jets upwards with wavy tentacles
🐻 Bear	`DitherAnimalType.bear`	Radial expand, rhythmic happy celebration dance
🦁 Lion	`DitherAnimalType.lion`	Regal radial reveal, mane puff & roaring motion
🐯 Tiger	`DitherAnimalType.tiger`	Stealth prowl, horizontal stalk & fierce eyes
🐶 Dog	`DitherAnimalType.dog`	Happy tilt, fast tail wagging & eager ears
🐼 Panda	`DitherAnimalType.panda`	Cozy chew, leisurely bamboo munching
🐷 Pig	`DitherAnimalType.pig`	Bouncy snuffle, nose wiggle & floppy ears
🦊 Fox	`DitherAnimalType.fox`	Sly diagonal sweep, fluffy bushy tail flick
🐵 Monkey	`DitherAnimalType.monkey`	Dynamic swing, playful vine swaying
🦆 Duck	`DitherAnimalType.duck`	Water wobble, rhythmic quacking & head bobbing
🐑 Sheep	`DitherAnimalType.sheep`	Fluffy expansion, joyful springy boings
🦔 Hedgehog	`DitherAnimalType.hedgehog`	Scuttle across, defensive bristle & twitch
☀️ Sun	`DitherAnimalType.sun`	Solar flare burst, radiant rays wiggle & smile
🌧️ Cloud	`DitherAnimalType.cloud`	Airy float, gently drizzles raindrops
🌙 Moon	`DitherAnimalType.moon`	Sleepy twilight rock, glowing serene crescent
⭐ Star	`DitherAnimalType.star`	Cosmic sparkle burst, bright twinkling rays
👻 Ghost	`DitherAnimalType.ghost`	Ethereal float, undulating floating "boo!"
🍄 Mushroom	`DitherAnimalType.mushroom`	Springy pop-up, bouncy jelly cap hop
🌵 Cactus	`DitherAnimalType.cactus`	Desert ground reveal, resilient desert sway
🤖 Robot	`DitherAnimalType.robot`	Vertical blinds scan, boot sequence & antenna pulse
🚀 Rocket	`DitherAnimalType.rocket`	Fiery countdown, thruster rumble & blast-off
🧁 Cupcake	`DitherAnimalType.cupcake`	Delicious drop, frosting swirl & jelly wobble

🎛️ API Reference

`DitherAnimal`

Property	Type	Default	Description
`animal`	`DitherAnimalType`	`DitherAnimalType.owl`	The built-in animal type to render.
`color`	`Color`	`Color(0xFF1F3BFF)`	Primary ink / dot color.
`cells`	`int`	`96`	Number of dots across the grid (higher = finer stipple).
`dot`	`DitherDot`	`DitherDot.square`	Dot shape: `DitherDot.square` or `DitherDot.round`.
`dotScale`	`double`	`0.9`	Dot size scaling factor (0.0 to 1.0+).
`motion`	`DitherMotion`	`DitherMotion.loop`	`loop` (infinite animation cycle) or `once` (assemble and freeze).
`duration`	`Duration?`	`null`	Total loop duration. Defaults to the animal's natural tempo.
`phase`	`double`	`0.0`	0..1 timing offset to stagger multiple animals out of sync.
`pokeable`	`bool`	`true`	When `true`, tapping triggers haptic feedback and a ripple wave.
`showFace`	`bool`	`true`	Draws glossy eyes, blush cheeks, and fine detail linework.
`sparkles`	`bool`	`true`	Emits a sparkle burst once the animal completes forming.
`shimmer`	`double`	`0.07`	Subtle edge flicker intensity while fully formed.
`image`	`ImageProvider?`	`null`	Custom image to dither instead of built-in animals.
`invertImage`	`bool`	`false`	Inverts image brightness when custom `image` is passed.

🖼️ Custom Image Dithering

You can dither any custom bitmap or artwork (dark graphics on transparent or light backgrounds look best):

DitherAnimal(
  image: const AssetImage('assets/logo.png'),
  color: Colors.deepPurple,
  cells: 112,
  dot: DitherDot.round,
  motion: DitherMotion.loop,
)

📱 Interactive Example App

The repository includes a complete example gallery demonstrating all 30 animals, search filtering, dot style toggle, grid density sliders, and interactive poke animations.

To run the example app:

cd example
flutter pub get
flutter run

📄 License

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