Shimmer Effects #

A modern, highly customizable shimmer effect widget for Flutter. Create beautiful skeleton loading states with ease.

Demo Gallery #

Features #

• Multiple directions - Left-to-right, right-to-left, top-to-bottom, bottom-to-top
• Smooth bounce mode - Optional ping-pong loop for seamless shimmer
• External control - Synchronize multiple shimmers with ShimmerController
• Accessibility - Respects system "Reduce Motion" settings
• Performance optimized - Built-in RepaintBoundary for efficient rendering in lists
• Finite loops - Run animation a specific number of times with completion callback
• Custom gradients - Full control over colors, stops, and blend modes
• Dark mode support - ShimmerLoading automatically adapts to theme brightness
• Pre-built skeletons - Ready-to-use skeleton widgets for common UI patterns

Installation #

Add shimmer effects to your pubspec.yaml:

dependencies:
  flutter_shimmer_effects: ^1.0.0

Then run:

flutter pub get

Quick Start #

Basic Usage #

import 'package:flutter_shimmer_effects/flutter_shimmer_effects.dart';

Shimmer.fromColors(
  baseColor: Colors.grey[300]!,
  highlightColor: Colors.grey[100]!,
  child: Container(
    width: 200,
    height: 100,
    color: Colors.white,
  ),
)

Loading State Management #

Use ShimmerLoading for automatic transitions between loading and content:

ShimmerLoading(
  isLoading: _isLoading,
  placeholder: SkeletonListTile(),
  child: ListTile(
    leading: CircleAvatar(backgroundImage: NetworkImage(user.avatar)),
    title: Text(user.name),
    subtitle: Text(user.email),
  ),
)

API Reference #

Shimmer #

The core widget that applies an animated gradient mask over its child.

Shimmer.fromColors

Convenience constructor using two colors:

Shimmer.fromColors(
  baseColor: Colors.grey[300]!,
  highlightColor: Colors.grey[100]!,
  child: YourWidget(),
)

ShimmerDirection #

Defines the direction of the shimmer gradient movement:

ShimmerController #

Manages animation state for one or more Shimmer widgets.

final controller = ShimmerController();

// Control animation
controller.start();
controller.stop();
controller.toggle();

// Check state
controller.isAnimating;
controller.isDisposed;

// Don't forget to dispose
controller.dispose();

Use cases:

• Synchronize multiple shimmer widgets
• Pause animation when content is off-screen
• Programmatically control animation based on app logic

ShimmerLoading #

A convenience widget that manages loading state transitions:

ShimmerLoading(
  isLoading: true,
  placeholder: SkeletonParagraph(lines: 3),
  child: Text('Loaded content'),
  fadeTransition: true,
  fadeDuration: Duration(milliseconds: 250),
)

Skeleton Widgets #

Pre-built skeleton widgets for common UI patterns:

SkeletonLine #

A rectangular skeleton for text lines:

SkeletonLine(
  width: double.infinity,
  height: 14.0,
  borderRadius: BorderRadius.circular(4),
)

SkeletonAvatar #

A circular skeleton for avatars:

SkeletonAvatar(size: 40.0)

SkeletonBox #

A rectangular skeleton for images or cards:

SkeletonBox(
  width: 100,
  height: 100,
  borderRadius: BorderRadius.circular(8),
)

SkeletonListTile #

A composite skeleton mimicking ListTile:

SkeletonListTile(
  hasLeading: true,
  hasSubtitle: true,
  leadingSize: 40.0,
  titleWidthFactor: 0.72,
  subtitleWidthFactor: 0.52,
)

SkeletonParagraph #

Multiple lines simulating a paragraph:

SkeletonParagraph(
  lines: 3,
  lineHeight: 14.0,
  spacing: 8.0,
  lastLineWidthFactor: 0.65,
)

Examples #

List Loading #

ListView.builder(
  itemCount: 10,
  itemBuilder: (context, index) {
    return ShimmerLoading(
      isLoading: _items == null,
      placeholder: SkeletonListTile(),
      child: _items != null ? ItemTile(item: _items[index]) : SizedBox(),
    );
  },
)

Card Skeleton #

Shimmer.fromColors(
  baseColor: Colors.grey[300]!,
  highlightColor: Colors.grey[100]!,
  child: Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      SkeletonBox(width: double.infinity, height: 200),
      SizedBox(height: 16),
      SkeletonParagraph(lines: 2),
    ],
  ),
)

Synchronized Shimmers #

class _MyWidgetState extends State<MyWidget> {
  final _controller = ShimmerController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Shimmer.fromColors(
          controller: _controller,
          baseColor: Colors.grey[300]!,
          highlightColor: Colors.grey[100]!,
          child: SkeletonLine(),
        ),
        Shimmer.fromColors(
          controller: _controller,
          baseColor: Colors.grey[300]!,
          highlightColor: Colors.grey[100]!,
          child: SkeletonLine(),
        ),
        ElevatedButton(
          onPressed: _controller.toggle,
          child: Text('Toggle'),
        ),
      ],
    );
  }
}

Finite Animation with Callback #

Shimmer.fromColors(
  baseColor: Colors.grey[300]!,
  highlightColor: Colors.grey[100]!,
  loop: 3,
  onAnimationComplete: () {
    print('Animation completed!');
  },
  child: Text('Highlight me'),
)

Custom Gradient #

Shimmer(
  gradient: LinearGradient(
    colors: [Colors.red, Colors.orange, Colors.yellow],
    stops: [0.0, 0.5, 1.0],
  ),
  child: Icon(Icons.star, size: 48),
)

Vertical Shimmer #

Shimmer.fromColors(
  direction: ShimmerDirection.ttb,
  baseColor: Colors.blue[300]!,
  highlightColor: Colors.blue[100]!,
  child: Container(width: 100, height: 200, color: Colors.white),
)

Performance Tips #

1. RepaintBoundary - Enabled by default. Keep it on when using shimmer in lists.

2. Controller for off-screen content - Stop animation when widgets scroll out of view:

   controller.stop(); // When off-screen
   controller.start(); // When visible again
   

3. Avoid deep nesting - Keep shimmer children relatively simple for best performance.

Accessibility #

By default, Shimmer respects the user's "Reduce Motion" system setting. When reduced motion is enabled:

• Animation stops
• Gradient freezes at staticPercent position (default: 0.5)

To override this behavior, set respectReducedMotion: false.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

MIT License - see the LICENSE file for details.