Zeba Academy Error State

Pub Version Pub Points Likes License: GPL v3

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

Copyright (C) 2026 Sufyan bin Uzayr.

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!

Libraries

zeba_academy_error_state