skeleton_builder #

A Flutter package for creating beautiful, animated skeleton loading screens with minimal code.

Features #

• One-line usage - Simple API for quick implementation
• Auto-detects layouts - Automatically generates skeletons for Row, Column, ListTile, Text, and more
• Pre-built components - SkeletonList, SkeletonGrid, and SkeletonForm ready to use
• Dark mode support - Automatic theme detection with customizable colors
• Customizable animations - Control duration, curve, and colors
• Performance optimized - Uses RepaintBoundary and efficient rendering
• Cross-platform - Works on iOS, Android, Web, macOS, Windows, and Linux

Installation #

Add this to your pubspec.yaml:

dependencies:
  skeleton_builder: ^0.0.1

Then run:

flutter pub get

Usage #

Import the package #

import 'package:skeleton_builder/skeleton_builder.dart';

SkeletonList #

Display a loading skeleton for list views:

SkeletonList(
  itemCount: 6,
)

With custom theme:

SkeletonList(
  itemCount: 6,
  theme: SkeletonTheme(
    baseColor: Colors.grey.shade300,
    highlightColor: Colors.grey.shade100,
    animationDuration: Duration(milliseconds: 1500),
    curve: Curves.easeInOut,
  ),
)

SkeletonGrid #

Display a loading skeleton for grid views:

SkeletonGrid(
  crossAxisCount: 2,
  itemCount: 6,
  itemHeight: 150,
)

SkeletonForm #

Display a loading skeleton for forms:

SkeletonForm(
  fieldCount: 4,
  theme: SkeletonTheme.light(),
)

SkeletonBuilder #

Auto-detect and replace any widget with its skeleton equivalent:

SkeletonBuilder(
  isLoading: _isLoading,
  child: Column(
    children: [
      Text('Title'),
      Row(
        children: [
          CircleAvatar(),
          Text('Subtitle'),
        ],
      ),
    ],
  ),
)

SkeletonBuilder.form() #

One-line form skeleton:

SkeletonBuilder.form(
  isLoading: _isLoading,
  fieldCount: 3,
)

Custom Animation #

Customize the shimmer animation:

SkeletonList(
  itemCount: 5,
  theme: SkeletonTheme(
    baseColor: Colors.grey.shade400,
    highlightColor: Colors.grey.shade200,
    animationDuration: Duration(seconds: 2),
    curve: Curves.easeInOutCubic,
  ),
)

Dark Mode #

Use the built-in dark theme:

SkeletonList(
  theme: SkeletonTheme.dark(),
)

Or with custom dark colors:

SkeletonTheme.dark(
  duration: Duration(milliseconds: 1200),
  curve: Curves.linear,
)

Components #

SkeletonTheme #

SkeletonList #

SkeletonGrid #

SkeletonForm #

SkeletonContainer #

Example #

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

class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    // Simulate loading
    Future.delayed(Duration(seconds: 2), () {
      setState(() => _isLoading = false);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: _isLoading
          ? const SkeletonList(itemCount: 10)
          : ListView.builder(
              itemCount: 10,
              itemBuilder: (context, index) => ListTile(
                leading: CircleAvatar(child: Text('$index')),
                title: Text('Item $index'),
                subtitle: Text('Description for item $index'),
              ),
            ),
    );
  }
}

Advanced Usage #

Using ShimmerHost directly #

For custom skeleton layouts, wrap your content with ShimmerHost:

ShimmerHost(
  theme: SkeletonTheme.light(),
  child: Column(
    children: [
      SkeletonContainer(
        height: 200,
        theme: SkeletonTheme.light(),
      ),
      SizedBox(height: 16),
      SkeletonContainer(
        height: 20,
        width: 150,
        theme: SkeletonTheme.light(),
      ),
    ],
  ),
)

Performance Tips #

1. The package automatically uses RepaintBoundary to optimize rendering
2. Skeleton widgets check for existing ShimmerController to avoid nested animations
3. Use const constructors where possible for better performance

License #

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

Contributing #

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

Issues #

If you encounter any issues or have feature requests, please file them on the issue tracker.