Zeba Academy Error View

A lightweight, customizable Flutter package for displaying consistent error states across your applications.

zeba_academy_error_view provides ready-to-use error-state widgets with customizable icons, messages, retry actions, layouts, spacing, colors, and typography.

Build clean error screens without repeatedly creating the same error-state UI.

Features

Simple and reusable error-state widgets.
Standard error view.
Compact error view.
Full-page error view.
Customizable error icons.
Customizable icon size and color.
Customizable error title and message.
Customizable text styles.
Optional retry action.
Customizable retry button text.
Customizable retry button style.
Configurable padding and spacing.
Configurable text alignment.
Configurable message line limits.
Material 3 theme support.
Accessibility-friendly retry actions.
Null-safe API.
No external dependencies.
Lightweight and easy to integrate.
Fully testable Flutter widgets.

Installation

Add zeba_academy_error_view to your pubspec.yaml:

dependencies:
  zeba_academy_error_view: ^0.0.1

Then run:

flutter pub get

Or install the latest version from:

pub.dev - zeba_academy_error_view

Import

import 'package:zeba_academy_error_view/zeba_academy_error_view.dart';

Basic Usage

The standard error view can be used anywhere an application needs to communicate that something went wrong.

ZebaErrorView(
  title: 'Something went wrong',
  message: 'We could not load the requested content.',
  onRetry: () {
    // Retry your request.
  },
)

Standard Error View

ZebaErrorView is the general-purpose widget for displaying an error state.

Scaffold(
  body: ZebaErrorView(
    title: 'Unable to load customers',
    message: 'Please check your internet connection and try again.',
    onRetry: () {
      debugPrint('Retry pressed');
    },
  ),
)

Without Retry

The retry action is optional.

const ZebaErrorView(
  title: 'No data available',
  message: 'There is currently no information to display.',
)

When onRetry is null, the retry button is automatically hidden.

Custom Icon

You can replace the default error icon.

ZebaErrorView(
  title: 'Connection Failed',
  message: 'Please check your network connection.',
  icon: Icons.wifi_off,
  onRetry: () {},
)

Another example:

ZebaErrorView(
  title: 'Server Unavailable',
  message: 'The server is temporarily unavailable.',
  icon: Icons.cloud_off,
  onRetry: () {},
)

Custom Icon Color

ZebaErrorView(
  title: 'Warning',
  message: 'Something needs your attention.',
  icon: Icons.warning_amber_rounded,
  iconColor: Colors.orange,
  onRetry: () {},
)

If iconColor is not provided, the widget uses the theme's error color.

Custom Icon Size

ZebaErrorView(
  title: 'Something went wrong',
  message: 'Please try again later.',
  iconSize: 72,
  onRetry: () {},
)

Custom Retry Button

The retry label can be changed to match your application.

ZebaErrorView(
  title: 'Request Failed',
  message: 'Unable to complete the request.',
  retryLabel: 'Reload',
  onRetry: () {
    debugPrint('Reload requested');
  },
)

Custom Text Styles

ZebaErrorView(
  title: 'Unable to continue',
  message: 'Please try again later.',
  titleStyle: const TextStyle(
    fontSize: 22,
    fontWeight: FontWeight.bold,
  ),
  messageStyle: const TextStyle(
    fontSize: 16,
  ),
  onRetry: () {},
)

When custom styles are not supplied, the widget automatically uses the current Flutter theme.

Custom Spacing

ZebaErrorView(
  title: 'Something went wrong',
  message: 'Please try again.',
  spacing: 20,
  onRetry: () {},
)

Custom Padding

ZebaErrorView(
  title: 'Something went wrong',
  message: 'Please try again.',
  padding: const EdgeInsets.symmetric(
    horizontal: 32,
    vertical: 48,
  ),
  onRetry: () {},
)

Compact Error View

ZebaCompactErrorView is designed for smaller areas such as:

Cards
Lists
Dialogs
Dashboard sections
Individual content sections

Example:

ZebaCompactErrorView(
  message: 'Unable to load payments.',
  onRetry: () {
    debugPrint('Retry payments');
  },
)

Compact View Without Retry

const ZebaCompactErrorView(
  message: 'Unable to load data.',
)

Custom Compact Icon

ZebaCompactErrorView(
  message: 'No connection available.',
  icon: Icons.wifi_off,
  iconColor: Colors.orange,
  onRetry: () {},
)

Full-Page Error View

ZebaFullPageErrorView is intended for situations where an entire screen cannot be displayed.

Scaffold(
  body: ZebaFullPageErrorView(
    title: 'Something went wrong',
    message: 'We could not load your dashboard.',
    onRetry: () {
      debugPrint('Retry dashboard');
    },
  ),
)

Full-Page Customization

ZebaFullPageErrorView(
  title: 'Server Error',
  message: 'The service is temporarily unavailable.',
  icon: Icons.cloud_off,
  iconSize: 96,
  iconColor: Colors.red,
  retryLabel: 'Try Again',
  backgroundColor: Colors.grey.shade100,
  onRetry: () {
    debugPrint('Retry requested');
  },
)

Using With Async Data

The package can easily be used with loading, success, and error states.

Widget buildContent() {
  if (hasError) {
    return ZebaFullPageErrorView(
      title: 'Unable to load data',
      message: 'Please try again.',
      onRetry: loadData,
    );
  }

  if (isLoading) {
    return const Center(
      child: CircularProgressIndicator(),
    );
  }

  return const YourContentWidget();
}

Using Inside a List

The compact widget works well when only one section of a screen fails.

Column(
  children: [
    const Text('Recent Payments'),
    const SizedBox(height: 16),
    if (hasError)
      ZebaCompactErrorView(
        message: 'Unable to load recent payments.',
        onRetry: loadPayments,
      )
    else
      const PaymentsList(),
  ],
)

Accessibility

Retry actions are wrapped with Flutter Semantics widgets so assistive technologies can identify them as buttons.

For example:

ZebaErrorView(
  title: 'Unable to load content',
  message: 'Please try again.',
  retryLabel: 'Retry',
  onRetry: loadContent,
)

The retry action exposes the configured label to accessibility services.

Material 3 Support

The package automatically reads colors and typography from the application's current ThemeData.

For example:

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorSchemeSeed: Colors.blue,
  ),
  home: const MyHomePage(),
)

The widgets use:

ColorScheme.error
ColorScheme.surface
ColorScheme.onSurfaceVariant
TextTheme

when custom values are not supplied.

API Overview

`ZebaErrorView`

General-purpose error-state widget.

Property	Type	Default
`title`	`String`	`Something went wrong`
`message`	`String`	`We could not load the requested content.`
`icon`	`IconData`	`Icons.error_outline`
`iconSize`	`double`	`64`
`iconColor`	`Color?`	Theme error color
`titleStyle`	`TextStyle?`	Theme style
`messageStyle`	`TextStyle?`	Theme style
`retryLabel`	`String`	`Retry`
`onRetry`	`VoidCallback?`	`null`
`spacing`	`double`	`12`
`buttonStyle`	`ButtonStyle?`	Theme style
`padding`	`EdgeInsetsGeometry`	`EdgeInsets.all(24)`
`textAlign`	`TextAlign`	`TextAlign.center`
`maxMessageLines`	`int?`	`null`

`ZebaCompactErrorView`

Compact error-state widget.

Property	Type	Default
`message`	`String`	`Unable to load content.`
`icon`	`IconData`	`Icons.error_outline`
`iconSize`	`double`	`32`
`iconColor`	`Color?`	Theme error color
`messageStyle`	`TextStyle?`	Theme style
`retryLabel`	`String`	`Retry`
`onRetry`	`VoidCallback?`	`null`
`spacing`	`double`	`8`
`padding`	`EdgeInsetsGeometry`	`EdgeInsets.all(16)`
`buttonStyle`	`ButtonStyle?`	Theme style
`textAlign`	`TextAlign`	`TextAlign.center`

`ZebaFullPageErrorView`

Full-screen error-state widget.

Property	Type	Default
`title`	`String`	`Something went wrong`
`message`	`String`	`We could not load this page.`
`icon`	`IconData`	`Icons.error_outline`
`iconSize`	`double`	`80`
`iconColor`	`Color?`	Theme error color
`titleStyle`	`TextStyle?`	Theme style
`messageStyle`	`TextStyle?`	Theme style
`retryLabel`	`String`	`Try Again`
`onRetry`	`VoidCallback?`	`null`
`spacing`	`double`	`16`
`padding`	`EdgeInsetsGeometry`	`EdgeInsets.all(32)`
`buttonStyle`	`ButtonStyle?`	Theme style
`backgroundColor`	`Color?`	Theme surface
`textAlign`	`TextAlign`	`TextAlign.center`

Example Application

A complete example:

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

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

  @override
  State<ErrorExamplePage> createState() => _ErrorExamplePageState();
}

class _ErrorExamplePageState extends State<ErrorExamplePage> {
  bool hasError = true;

  void retry() {
    setState(() {
      hasError = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Error View'),
      ),
      body: hasError
          ? ZebaFullPageErrorView(
              title: 'Unable to load content',
              message: 'Please check your connection and try again.',
              onRetry: retry,
            )
          : const Center(
              child: Text('Content loaded successfully!'),
            ),
    );
  }
}

Testing

Run the package tests with:

flutter test

Run static analysis with:

flutter analyze

Format the project with:

dart format lib test

Validate the package before publishing:

flutter pub publish --dry-run

Design Goals

zeba_academy_error_view is designed around a few principles:

Simple

Common error states should require only a few lines of code.

Customizable

Applications should be able to adapt the widgets to their own design systems.

Lightweight

The package has no third-party runtime dependencies.

Reusable

The same error-state components can be used throughout an application.

Accessible

Interactive retry actions provide semantic information for accessibility services.

Theme-aware

The widgets integrate naturally with Flutter's existing theme system.

Dependencies

This package has no external dependencies.

It only depends on Flutter's built-in framework.

Compatibility

The package is designed for Flutter applications using null safety.

Minimum Dart SDK:

^3.12.0

Minimum Flutter SDK:

>=1.17.0

Contributing

Contributions, bug reports, feature requests, and improvements are welcome.

Before submitting a pull request:

flutter analyze
flutter test
dart format lib test
flutter pub publish --dry-run

Please keep changes focused, tested, documented, and compatible with the package's existing public API.

Issues and Feature Requests

If you encounter a problem or have an idea for improving the package, please open an issue in the project's repository.

License

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

See the LICENSE file for the complete license text.

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!

📚 Zeba Academy is focused on helping developers learn, build, and grow through practical programming resources and open-source projects.

Explore the Zeba Academy ecosystem:

Author

Sufyan bin Uzayr

Website: sufyanism.com
LinkedIn: Sufyan bin Uzayr on LinkedIn

Support

If this package is useful to you, consider supporting the project by:

⭐ Giving the project a star.
📦 Using the package in your Flutter projects.
🐛 Reporting bugs.
💡 Suggesting improvements.
🤝 Contributing to the project.
📖 Sharing it with other Flutter developers.

Made with ❤️ for the Flutter community by Zeba Academy.