🦴 Mirror Skeleton

Render-tree aware shimmer skeletons for Flutter. Wrap any widget tree in one line — MirrorSkeleton walks the actual RenderObject tree and generates pixel-matched bones for every text run, image, container, button, form control, and progress indicator it finds. Zero layout shift when your data arrives.

---

✨ The 30-Second Pitch

MirrorSkeleton(
  isLoading: loading,
  child: YourPage(),
);

That's it. No parallel placeholder tree to maintain, no per-widget shimmer config. Edit your real UI and the skeleton stays in sync — automatically.

---

---

🎬 Demo

---

---

🎯 Why Mirror Skeleton

Most skeleton libraries make you hand-craft a parallel widget tree that mirrors your real UI, doubling maintenance every time the design shifts. mirror_skeleton inspects the laid-out render tree at paint time and projects a shape for every visible element it finds.

Feature	Hand-crafted skeleton	mirror_skeleton
Match your real UI	manual	✅ automatic
Survives design changes	rewrite	✅ free
Zero layout shift	only if pixel-perfect	✅ always
Multi-line text wrapping	manual line-count math	✅ automatic
Theme-tinted color	manual	✅ automatic
Excluded brand elements	custom logic	✅ SkeletonIgnore
Buttons / chips / form controls	manual placeholders	✅ auto-detected
Hides children from screen readers	manual ExcludeSemantics	✅ built in
Blocks taps during loading	manual IgnorePointer	✅ built in
Smooth crossfade when loaded	manual AnimatedSwitcher	✅ built in
Honors reduced-motion setting	manual	✅ built in
Multiple animation styles	manual	✅ shimmer / pulse / fade / wave

---

🚀 Quick Start (2 Steps!)

Step 1: Add to Dependencies

# pubspec.yaml
dependencies:
  mirror_skeleton: ^0.3.0

Then run:

flutter pub get

Step 2: Wrap Your Widget Tree

import 'package:mirror_skeleton/mirror_skeleton.dart';

MirrorSkeleton(
  isLoading: _loading,
  child: ProfileBody(user: _user ?? User.placeholder()),
);

That's it! 🎉 The widget tree under child renders as-is when isLoading is false. While isLoading is true, the same tree is walked at paint time and replaced with shimmering bones matching every visible element — at the exact same positions and sizes.

---

📖 Complete Usage Guide

🦴 Basic Skeleton Wrap

class ProfileScreen extends StatefulWidget {
  @override
  State<ProfileScreen> createState() => _ProfileScreenState();
}

class _ProfileScreenState extends State<ProfileScreen> {
  bool _loading = true;
  User? _user;

  @override
  void initState() {
    super.initState();
    _fetchUser();
  }

  Future<void> _fetchUser() async {
    final user = await api.getUser();
    setState(() {
      _user = user;
      _loading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return MirrorSkeleton(
      isLoading: _loading,
      child: ProfileBody(user: _user ?? User.placeholder()),
    );
  }
}

When _loading flips off, the real content fades in over a smooth 250ms crossfade. No visible pop, no jump.

🛡️ Keep Brand Elements Visible with SkeletonIgnore

Wrap any subtree in SkeletonIgnore to opt it out of skeletonization:

MirrorSkeleton(
  isLoading: _loading,
  child: Column(
    children: [
      SkeletonIgnore(
        child: Image.asset('assets/logo.png'), // stays visible & tappable
      ),
      ProfileBody(user: user), // shimmers
    ],
  ),
);

The logo stays fully painted while everything around it shimmers. Useful for:

• Brand logos and hero illustrations
• Navigation rails / app bars you want to keep functional
• Background patterns and decorative imagery
• Any element that should stay visible during loading

🎨 Customize the Look

MirrorSkeleton(
  isLoading: loading,
  shimmerColor: Colors.indigo.shade100,         // optional — bone color
  shimmerDuration: Duration(seconds: 2),        // sweep duration (default 1500ms)
  transitionDuration: Duration(milliseconds: 200), // crossfade out (default 250ms)
  adaptiveSpeed: true,                          // slow shimmer on jank
  shimmerHighlightColor: Colors.white,          // moving highlight color
  shimmerHighlightIntensity: 0.35,              // peak alpha 0.0–1.0
  shimmerDirection: ShimmerDirection.leftToRight,
  style: MirrorSkeletonStyle.shimmer,           // shimmer / pulse / fade / wave
  child: YourPage(),
);

When shimmerColor is omitted, MirrorSkeleton derives a tone from Theme.of(context).colorScheme.primary so the loading state always feels native to your brand — light or dark mode.

🌊 Animation Styles

Pick the loading vibe that fits your app:

// Default — sweeping highlight
MirrorSkeleton(
  isLoading: loading,
  style: MirrorSkeletonStyle.shimmer,
  child: YourPage(),
);

// Calm in-place opacity oscillation (~55% → 100%)
MirrorSkeleton(
  isLoading: loading,
  style: MirrorSkeletonStyle.pulse,
  child: YourPage(),
);

// Deeper blink (~20% → 100%) — more pronounced
MirrorSkeleton(
  isLoading: loading,
  style: MirrorSkeletonStyle.fade,
  child: YourPage(),
);

// Per-bone wave that travels along the shimmer axis
MirrorSkeleton(
  isLoading: loading,
  style: MirrorSkeletonStyle.wave,
  child: YourPage(),
);

↔️ Shimmer Direction (4 Options)

ShimmerDirection.leftToRight   // ➡️  Default
ShimmerDirection.rightToLeft   // ⬅️
ShimmerDirection.topToBottom   // ⬇️
ShimmerDirection.bottomToTop   // ⬆️

MirrorSkeleton(
  isLoading: loading,
  shimmerDirection: ShimmerDirection.topToBottom,
  child: YourPage(),
);

---

🎯 Auto-Detected Widgets

Anything in this list becomes a properly-shaped bone with no extra code:

📝 Text & Icons

• Text, RichText — multi-line text emits one bone per visual line at the actual wrapped width
• Icon — chunky rounded-square bone matching the icon's footprint

🖼️ Images

• Image.asset, Image.network, Image.file, Image.memory
• ClipRRect / ClipOval shapes propagate to descendant images (a ClipRRect(borderRadius: 16) wrapping an image gives a bone with radius 16)

📦 Containers & Surfaces

• Container(color: ...), Container(decoration: ...), ColoredBox, DecoratedBox
• BoxShape.circle becomes a circle bone; rectangular shapes preserve borderRadius
• Card, Material — emits a low-opacity backdrop for the surface, then layers inner content bones on top (the same pattern production skeletons use for gradient cards, hero artwork, analytics panels, etc.)

👤 Avatars

• CircleAvatar of any size

🔘 Buttons & Chips

• ElevatedButton, FilledButton, OutlinedButton, TextButton
• IconButton, FloatingActionButton
• Chip, ActionChip, InputChip

☑️ Form Controls (look like the real widget)

• TextField, TextFormField — full-field rounded rect
• Switch — pill track + thumb circle
• Slider — thin track + thumb
• Radio — stroked ring
• Checkbox — outlined rounded square

⏳ Progress (intentionally not skeletonised)

• A real CircularProgressIndicator, LinearProgressIndicator, or RefreshProgressIndicator is a different kind of loading affordance — stamping a pill on top would be misleading. Their subtree is skipped entirely. Third-party widgets whose render-object class name contains Progress, Loader, or Spinner are also skipped.

📊 Custom Charts (shape-aware)

Leaf CustomPaint widgets are detected by aspect:

• Square small (donut, pie, gauge) → circle bone
• Wide (sparkline, bar, line, area) → row of varying-height bar bones, so the loading state actually signals "chart"
• Anything else → rounded-rect fallback

➖ Dividers

• Thin border-only decorations render as a hairline bone

📐 Layout Widgets (traversed)

Row, Column, Stack, Padding, SizedBox, AspectRatio, Expanded, Flexible, ListView, GridView, SingleChildScrollView, CustomScrollView — traversed and used to compute exact bone positions via RenderBox.localToGlobal.

---

🛠️ Built-in Polish

Things you don't have to remember to wire up:

• 🚫 Hit testing absorbed during loading. Taps don't leak through to underlying widgets — onPressed handlers won't fire while the skeleton is up.
• 🔇 Semantics excluded during loading. Screen readers see a single Loading live region instead of reading placeholder text.
• 🎬 Smooth crossfade when isLoading flips off. Real content fades in over transitionDuration (250ms by default) — no visible pop.
• ♿ Reduced motion respected. When MediaQuery.of(context).disableAnimations is true, the shimmer stops sweeping and the bones stay static.
• ⚡ Adaptive shimmer speed. Frame timings are sampled and the shimmer slows automatically on devices that drop frames.
• 💤 TickerMode-aware. A MirrorSkeleton inside an off-screen TabBarView page (or any TickerMode(enabled: false) subtree) stops its shimmer ticker so it doesn't burn frames when invisible.
• 📐 Zero layout shift. Bones are derived from the laid-out subtree, so the real content slots into exactly the same coordinates.
• 🧹 Memory released after fade-out. When the crossfade completes, the bone list, ignored-region list, and descendant cache are cleared so the render object stops pinning descendants in memory.

---

💡 Real-World Examples

Profile Page with Avatar, Bio & Stats

class ProfilePage extends StatefulWidget {
  @override
  State<ProfilePage> createState() => _ProfilePageState();
}

class _ProfilePageState extends State<ProfilePage> {
  bool _loading = true;
  User? _user;

  @override
  void initState() {
    super.initState();
    _load();
  }

  Future<void> _load() async {
    await Future.delayed(Duration(seconds: 2));
    setState(() {
      _user = await api.getUser();
      _loading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Profile')),
      body: MirrorSkeleton(
        isLoading: _loading,
        child: Column(
          children: [
            CircleAvatar(radius: 50, backgroundImage: NetworkImage(user.avatar)),
            Text(user.name, style: TextStyle(fontSize: 24)),
            Text(user.bio, maxLines: 3),
            Row(children: [
              StatChip(label: 'Followers', value: user.followers),
              StatChip(label: 'Following', value: user.following),
              StatChip(label: 'Posts', value: user.posts),
            ]),
          ],
        ),
      ),
    );
  }
}

Feed List with Hero Image Excluded

MirrorSkeleton(
  isLoading: _loading,
  child: CustomScrollView(
    slivers: [
      SliverToBoxAdapter(
        // Brand hero stays visible the whole time
        child: SkeletonIgnore(
          child: Image.asset('assets/hero.png'),
        ),
      ),
      SliverList.builder(
        itemBuilder: (_, i) => ArticleTile(article: articles[i]),
        itemCount: articles.length,
      ),
    ],
  ),
);

Tab View with Per-Tab Loading

TabBarView(
  children: [
    MirrorSkeleton(isLoading: _loadingFeed,    child: FeedPage()),
    MirrorSkeleton(isLoading: _loadingTrending, child: TrendingPage()),
    MirrorSkeleton(isLoading: _loadingSaved,   child: SavedPage()),
  ],
);

Each tab shimmers independently, and off-screen tabs pause their shimmer ticker automatically (TickerMode-aware) — no wasted frames.

Pull-to-Refresh

RefreshIndicator(
  onRefresh: _load,
  child: MirrorSkeleton(
    isLoading: _loading,
    child: ListView.builder(
      itemBuilder: (_, i) => ArticleTile(article: articles[i]),
      itemCount: articles.length,
    ),
  ),
);

The RefreshProgressIndicator is intentionally skipped during skeletonization, so the spinner remains visible above the shimmering list — exactly like production apps.

---

📚 API Reference

MirrorSkeleton

Parameter	Type	Default	Notes
isLoading	bool	required	Show skeleton vs. real child
child	Widget?	–	The tree to skeletonize
shimmerColor	Color?	derived from theme	Bone color. null → derived from Theme.of(context).colorScheme.primary
shimmerDuration	Duration	1500ms	One full sweep
transitionDuration	Duration	250ms	Crossfade duration. Duration.zero to disable
adaptiveSpeed	bool	true	Slow shimmer on frame drops
shimmerHighlightColor	Color	Colors.white	Color of the moving highlight
shimmerHighlightIntensity	double	0.35	Peak alpha of the highlight, 0.0–1.0
shimmerDirection	ShimmerDirection	leftToRight	Sweep direction
style	MirrorSkeletonStyle	shimmer	shimmer / pulse / fade / wave

SkeletonIgnore

Wraps a subtree and renders it normally over the skeleton. Useful for brand logos, hero illustrations, or anything that should remain visible during loading.

SkeletonIgnore(child: YourBrandWidget())

ShimmerDirection

enum ShimmerDirection { leftToRight, rightToLeft, topToBottom, bottomToTop }

MirrorSkeletonStyle

enum MirrorSkeletonStyle { shimmer, pulse, fade, wave }

Style	Effect
shimmer	Sweeping highlight gradient — the classic skeleton look
pulse	Calm in-place opacity oscillation (~55% ↔ 100%)
fade	Pronounced blink (~20% ↔ 100%)
wave	Per-bone alpha wave traveling along the shimmer axis — gentler than shimmer, shader-free

---

🧠 Best Practices

✅ Do's

• ✓ Wrap the smallest meaningful subtree (the body of a screen, a list, a card) — not the whole MaterialApp
• ✓ Render real widgets with placeholder data while loading — User.placeholder(), List.filled(6, Article.placeholder()) — so layout matches the loaded state
• ✓ Use SkeletonIgnore for brand logos, hero images, navigation chrome
• ✓ Trust the auto-detection — it covers virtually all standard Flutter widgets
• ✓ Test with dark mode — theme-derived colors adapt automatically

❌ Don'ts

• ✗ Don't toggle isLoading rapidly — let the crossfade finish for a polished feel
• ✗ Don't wrap a Scaffold directly — wrap the body, not the whole Scaffold (so the AppBar stays interactive)
• ✗ Don't worry about progress indicators inside the tree — they're auto-skipped, not skeletonized
• ✗ Don't forget to provide placeholder data to your widgets while loading; MirrorSkeleton shapes bones from what's actually laid out

---

🆘 Troubleshooting

Issue	Solution
Skeleton shows nothing	Make sure isLoading: true and that the child actually lays out (provide placeholder data so widgets get a real size)
Real content "pops" in	Increase transitionDuration for a softer crossfade, or set it to Duration.zero if you want a hard cut
Shimmer feels laggy	adaptiveSpeed: true is on by default — try release mode (flutter run --release) for true performance
Bones at wrong positions	Wrap a smaller subtree closer to the actual content, not the whole app
Logo gets shimmered	Wrap it in SkeletonIgnore
Custom widget not detected	Wrap it in a sized Container(color: ...) during loading, or use SkeletonIgnore to keep it visible
Rotated bone has no shimmer overlay	Known: Transform.rotate / RotatedBox bones are drawn at the correct rotated position but the shimmer highlight skips them — they still receive the bone color

---

⚠️ Limitations

• Transform.rotate / RotatedBox bones are drawn at the correct rotated position, but the moving shimmer highlight skips them — they still receive the bone color, just without the sweep overlay.
• Truly bespoke RenderBox subclasses outside the patterns above: fall back to wrapping in a Container(color: ...) of equivalent size during loading, or wrap in SkeletonIgnore to keep them visible.

---

📊 Quality & Testing

• ✅ 30/30 tests passing (100%)
• ✅ 0 code analysis issues
• ✅ Full null safety
• ✅ Dartdoc on all public API
• ✅ Flutter 3.27.0+
• ✅ Dart 3.11.3+

---

📁 Project Structure

mirror_skeleton/
├── lib/
│   ├── mirror_skeleton.dart          # Public entrypoint
│   └── src/
│       ├── render_mirror_skeleton.dart  # Render object & owner element
│       ├── bone_detection.dart       # Render-tree → bones
│       ├── bone_painting.dart        # Bones → canvas
│       └── bones.dart                # Bone, BoneType, ShimmerDirection, MirrorSkeletonStyle
├── test/
│   └── mirror_skeleton_test.dart     # 30 widget tests
├── example/                          # 14-page demo gallery
│   └── lib/
│       └── pages/                    # Profile, Feed, Grid, Article, Chat, Dashboard, Controls, …
└── pubspec.yaml

---

🎬 Example App

A complete demo gallery is in example/ covering:

• Profile — Avatar, multi-line bio, stat row
• Feed — ListView of article tiles with images
• Product Grid — GridView with cards, prices, ratings
• Article — Hero image, paragraphs, author row
• Messages / Conversations — Chat list with avatars and unread badges
• Dashboard — Mixed layout with SkeletonIgnore brand banner
• Controls Gallery — Buttons, chips, switches, sliders, progress, text fields
• Login — TextFields, password toggle, Checkbox, social buttons
• Settings — Sectioned ListTiles with Switch, Checkbox, Slider, Divider
• Music Player — Hero artwork, sliders, transport row, queue list
• Wallet — Gradient balance card, action chips, transaction list
• Analytics — Sparkline + bar + donut CustomPaint charts and stats
• Shimmer Styles — Live playground for direction, style, color, intensity

Run it:

cd example
flutter pub get
flutter run

---

🤝 Contributing

Contributions are welcome! Please:

1. Report issues on GitHub
2. Submit pull requests with improvements
3. Help improve documentation

---

📄 License

MIT License — see LICENSE for details.

---

📚 Resources

• Example App — Complete demo gallery with 14+ screens
• Changelog — Version history
• GitHub — Source code
• Pub.dev — Package registry

---