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

Property	Type	Default	Description
baseColor	Color	Grey 300/800	Base color of the skeleton
highlightColor	Color	Grey 100/600	Highlight color for shimmer effect
animationDuration	Duration	1500ms	Duration of one shimmer cycle
curve	Curve	Curves.linear	Animation curve

SkeletonList

Property	Type	Default	Description
itemCount	int	6	Number of skeleton items
theme	SkeletonTheme?	auto	Custom theme (auto-detects light/dark)

SkeletonGrid

Property	Type	Default	Description
crossAxisCount	int	2	Number of columns
itemCount	int	6	Number of skeleton items
itemHeight	double	120	Height of each item
theme	SkeletonTheme?	auto	Custom theme

SkeletonForm

Property	Type	Default	Description
fieldCount	int	3	Number of form fields
theme	SkeletonTheme	required	Theme for the skeleton

SkeletonContainer

Property	Type	Default	Description
height	double	16	Height of the container
width	double	double.infinity	Width of the container
borderRadius	BorderRadius	8	Border radius
theme	SkeletonTheme	required	Theme for the skeleton

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.