status_protocol #

A plug-and-play Flutter package for handling HTTP status code UI states with SVG illustrations, messages, and action buttons.

Features #

• StatusScreen — Full-page error screen for any HTTP status code
• StatusBanner — Compact inline banner for in-screen errors
• SVG illustrations — Per-status illustrations with icon fallback
• Customizable — Override title, message, button, colors, SVGs
• Themeable — Global theme via StatusProtocolProvider
• Framework agnostic — Works with BLoC, Riverpod, Provider, GetX
• All HTTP codes — 400–504, plus no-internet and unknown fallback

Install #

dependencies:
  status_protocol: ^1.0.0

Usage #

Full-screen error #

StatusScreen(
  statusCode: 404,
  onRetry: () => myApiCall(),
)

Inline banner #

StatusBanner(
  statusCode: 429,
  onRetry: () {},
  onDismiss: () {},
)

Custom overrides #

StatusScreen(
  statusCode: 500,
  onRetry: () {},
  title: 'Custom Title',
  message: 'Custom message',
  buttonLabel: 'Try Again',
  backgroundColor: Colors.black,
  accentColor: Colors.deepPurple,
  showButton: true,
  svgAsset: 'assets/svg/500.svg',
  customButton: MyCustomButton(),
)

With StatusProtocolProvider (global theme) #

MaterialApp(
  home: StatusProtocolProvider(
    backgroundColor: Color(0xFF0D0D0F),
    useSvg: true,
    child: MyApp(),
  ),
)

In a FutureBuilder #

FutureBuilder(
  future: myApi.getData(),
  builder: (ctx, snap) {
    if (snap.hasError) {
      final code = (snap.error as ApiException).statusCode;
      return StatusScreen(statusCode: code, onRetry: refetch);
    }
    return MyDataWidget(snap.data);
  },
)

With Dio interceptor #

dio.interceptors.add(InterceptorsWrapper(
  onError: (e, handler) {
    final code = e.response?.statusCode ?? 0;
    navigatorKey.currentState?.push(
      MaterialPageRoute(
        builder: (_) => StatusScreen(
          statusCode: code,
          onRetry: () => navigatorKey.currentState?.pop(),
        ),
      ),
    );
  },
));

Status Codes #

SVG Assets #

Place your SVG files in assets/svg/ matching the code names:

assets/svg/
├── noInternet.svg   (used for 0, -1, 4xx/5xx fallback)
├── 401.svg
├── 403.svg
├── 404.svg
├── 429.svg
├── 500.svg
├── 503.svg
├── 504.svg

Missing per-code SVGs fall back to noInternet.svg. To add a dedicated SVG, create e.g. 400.svg, 408.svg, etc. — they'll be picked up automatically.

License #

MIT