Zeba Academy Error State

A lightweight, reusable Flutter error state widget with customizable error messages, icons, retry actions, layouts, and Material 3 support.

Build clear and consistent error states for your Flutter applications without repeatedly creating the same UI from scratch.

Features

Display customizable error titles and messages
Optional error icon
Custom icon, size, and color
Built-in retry button
Custom retry button text
Retry callback support
Optional retry button
Custom title and message styles
Custom button styling
Configurable padding and spacing
Custom text alignment
Flexible horizontal and vertical alignment
Optional width and height constraints
Material 3 compatible
Null-safe
Lightweight
No external dependencies

Installation

Add the package to your pubspec.yaml:

dependencies:
  zeba_academy_error_state: ^0.0.1

Then run:

flutter pub get

Import

import 'package:zeba_academy_error_state/zeba_academy_error_state.dart';

Basic Usage

ZebaErrorState(
  title: 'Something went wrong',
  message: 'Unable to load the requested content.',
  onRetry: () {
    // Retry your operation.
  },
);

Complete Example

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

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Error State'),
      ),
      body: ZebaErrorState(
        title: 'Unable to load data',
        message: 'Please check your internet connection and try again.',
        onRetry: () {
          debugPrint('Retry pressed');
        },
      ),
    );
  }
}

Custom Retry Text

ZebaErrorState(
  title: 'Failed to load',
  message: 'The requested data could not be loaded.',
  retryText: 'Retry',
  onRetry: () {
    // Retry operation.
  },
);

Custom Icon

ZebaErrorState(
  title: 'No Internet Connection',
  message: 'Please check your network connection.',
  icon: Icons.wifi_off,
  onRetry: () {
    // Retry connection.
  },
);

Custom Icon Color and Size

ZebaErrorState(
  title: 'Server Error',
  message: 'The server is currently unavailable.',
  icon: Icons.cloud_off,
  iconSize: 72,
  iconColor: Colors.orange,
  onRetry: () {},
);

Hide the Icon

ZebaErrorState(
  title: 'Access Denied',
  message: 'You do not have permission to view this content.',
  showIcon: false,
  onRetry: () {},
);

Hide the Retry Button

The retry button is automatically hidden when onRetry is null.

ZebaErrorState(
  title: 'Access Denied',
  message: 'You do not have permission to view this content.',
  showRetryButton: false,
);

Custom Text Styles

ZebaErrorState(
  title: 'Payment Failed',
  message: 'Your payment could not be completed.',
  titleStyle: const TextStyle(
    fontSize: 24,
    fontWeight: FontWeight.bold,
  ),
  messageStyle: const TextStyle(
    fontSize: 16,
  ),
  onRetry: () {},
);

Custom Retry Button Style

ZebaErrorState(
  title: 'Something went wrong',
  message: 'Please try again later.',
  onRetry: () {},
  retryButtonStyle: ElevatedButton.styleFrom(
    padding: const EdgeInsets.symmetric(
      horizontal: 32,
      vertical: 14,
    ),
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
);

Compact Error State

ZebaErrorState(
  title: 'Failed to load',
  message: 'Try again.',
  iconSize: 40,
  padding: const EdgeInsets.all(12),
  spacing: 8,
  onRetry: () {},
);

API Reference

`ZebaErrorState`

Property	Type	Default	Description
`title`	`String`	`Something went wrong`	Error title
`message`	`String`	Default error message	Supporting error message
`retryText`	`String`	`Try Again`	Retry button label
`onRetry`	`VoidCallback?`	`null`	Callback triggered on retry
`icon`	`IconData`	`Icons.error_outline`	Error icon
`iconSize`	`double`	`64`	Icon size
`iconColor`	`Color?`	Theme error color	Icon color
`titleStyle`	`TextStyle?`	Theme style	Title text style
`messageStyle`	`TextStyle?`	Theme style	Message text style
`retryButtonStyle`	`ButtonStyle?`	Theme style	Retry button style
`retryTextStyle`	`TextStyle?`	Theme style	Retry text style
`padding`	`EdgeInsetsGeometry`	`EdgeInsets.all(24)`	Content padding
`spacing`	`double`	`12`	Spacing between elements
`showIcon`	`bool`	`true`	Whether to show the icon
`showRetryButton`	`bool`	`true`	Whether to show the retry button
`mainAxisAlignment`	`MainAxisAlignment`	`center`	Vertical alignment
`crossAxisAlignment`	`CrossAxisAlignment`	`center`	Horizontal alignment
`textAlign`	`TextAlign`	`center`	Text alignment
`width`	`double?`	`null`	Optional width
`height`	`double?`	`null`	Optional height

Real-World Example

class UserScreen extends StatefulWidget {
  const UserScreen({super.key});

  @override
  State<UserScreen> createState() => _UserScreenState();
}

class _UserScreenState extends State<UserScreen> {
  bool isLoading = false;
  bool hasError = true;

  Future<void> loadUsers() async {
    setState(() {
      isLoading = true;
      hasError = false;
    });

    await Future<void>.delayed(
      const Duration(seconds: 2),
    );

    setState(() {
      isLoading = false;
      hasError = true;
    });
  }

  @override
  Widget build(BuildContext context) {
    if (isLoading) {
      return const Center(
        child: CircularProgressIndicator(),
      );
    }

    if (hasError) {
      return ZebaErrorState(
        title: 'Failed to load users',
        message: 'We could not retrieve the user list.',
        onRetry: loadUsers,
      );
    }

    return const Center(
      child: Text('Users loaded successfully'),
    );
  }
}

Testing

Run the test suite:

flutter test

Analyze the package:

flutter analyze

Validate the package before publishing:

flutter pub publish --dry-run

Compatibility

This package supports:

Flutter >=1.17.0
Dart ^3.12.0
Material 3 applications
Null safety

License

This project is licensed under the GNU General Public License v3.0.

You should have received a copy of the GNU General Public License along with this project.

If not, see:

https://www.gnu.org/licenses/

About Me

✨ I’m Sufyan bin Uzayr, an open-source developer passionate about building and sharing meaningful projects.

You can learn more about me and my work at sufyanism.com or connect with me on LinkedIn.

Your All-in-One Learning Hub!

🚀 Explore courses and resources in coding, tech, and development at Zeba Academy.

Empower yourself with practical skills through curated tutorials, real-world projects, and hands-on experience. Level up your tech game today! 💻✨

Zeba Academy is a learning platform dedicated to coding, technology, and development.

➡ Visit our main site: zeba.academy

➡ Explore hands-on courses and resources at: code.zeba.academy

➡ Check out our YouTube for more tutorials: Zeba Academy

➡ Follow us on Instagram: Zeba Academy

Thank you for visiting!