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.

zeba_academy_error_view 0.0.1 zeba_academy_error_view: ^0.0.1 copied to clipboard

Metadata