dio_network_interceptor 1.0.0
dio_network_interceptor: ^1.0.0 copied to clipboard
A Dio interceptor that globally handles internet connectivity — blocks requests when offline, catches drops mid-transfer, and shows offline UI automatically.
dio_network_interceptor #
A Dio interceptor that globally handles internet connectivity — blocks requests when offline, catches drops mid-transfer, and shows offline UI automatically.
Features #
- Pre-request check — blocks requests before they're sent when offline
- Mid-response check — catches internet loss while data is being received
- Typed exceptions — all Dio errors mapped to
NetworkExceptionwith clear types - Global offline UI — show a dialog or full page automatically via
NetworkObserver - Per-page offline UI — wrap individual pages with
NetworkAwareWidget - Custom check URIs — override default connectivity check endpoints
Installation #
dependencies:
dio_network_interceptor: ^1.0.0
flutter pub get
Usage #
There are three ways to handle offline UI — pick what fits your app.
Type 1 — Snackbar (via onNoInternet callback) #
The simplest approach. Show a snackbar or any custom feedback when a request is blocked.
import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
import 'package:network_interceptor/network_interceptor.dart';
final dio = Dio();
// Call once — e.g. in initState or a DI setup
void setupDio(BuildContext context) {
dio.interceptors.add(
NetworkInterceptor(
onNoInternet: (requestOptions) async {
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(
content: Text('📵 No internet connection'),
backgroundColor: Colors.red,
),
);
},
onNetworkError: (exception) {
debugPrint('[NetworkError] ${exception.type}: ${exception.message}');
},
),
);
}
Catch errors in your repository:
try {
final response = await dio.get('/posts');
} on DioException catch (e) {
if (e.error is NetworkException) {
final error = e.error as NetworkException;
switch (error.type) {
case NetworkErrorType.noInternet:
// show offline UI
case NetworkErrorType.timeout:
// show retry button
case NetworkErrorType.serverError:
// use error.statusCode (401, 404, 500...)
case NetworkErrorType.cancelled:
// silently ignore
default:
// show generic error
}
}
}
Type 2 — Global dialog or page (NetworkObserver) #
Wrap your root MaterialApp once. A dialog or full page is shown/dismissed
automatically whenever connectivity changes — no per-screen code needed.
Setup
final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();
void main() => runApp(const MyApp());
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return NetworkObserver(
navigatorKey: navigatorKey, // required
// dialogBuilder: ... // optional — custom dialog
// pageBuilder: ... // optional — full offline page
child: MaterialApp(
navigatorKey: navigatorKey, // same key
home: const HomeScreen(),
),
);
}
}
Option A — Default dialog (nothing extra needed)
NetworkObserver(
navigatorKey: navigatorKey,
child: MaterialApp(...),
)
Option B — Custom dialog
NetworkObserver(
navigatorKey: navigatorKey,
dialogBuilder: (context) => AlertDialog(
icon: const Icon(Icons.signal_wifi_off, color: Colors.orange, size: 56),
title: const Text('You\'re Offline'),
content: const Text('Please reconnect and try again.'),
actions: [
TextButton(
onPressed: () => Navigator.pop(context),
child: const Text('OK'),
),
],
),
child: MaterialApp(...),
)
Option C — Full offline page
NetworkObserver(
navigatorKey: navigatorKey,
pageBuilder: (context) => Scaffold(
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
const Icon(Icons.wifi_off, size: 80, color: Colors.grey),
const SizedBox(height: 24),
const Text('You are Offline',
style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold)),
const SizedBox(height: 8),
const Text('Please check your internet connection.'),
],
),
),
),
child: MaterialApp(...),
)
Note:
pageBuildertakes priority overdialogBuilderwhen both are set.
Type 3 — Per-page wrapper (NetworkAwareWidget) #
Wrap individual pages that need their own offline UI. The child is swapped inline — no navigation, no dialog. Recovers automatically when internet returns.
import 'package:network_interceptor/network_interceptor.dart';
class ProductsPage extends StatelessWidget {
const ProductsPage({super.key});
@override
Widget build(BuildContext context) {
return NetworkAwareWidget(
// optional — custom offline UI for this page:
offlineBuilder: (context) => Scaffold(
appBar: AppBar(title: const Text('Products')),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
const Icon(Icons.cloud_off, size: 64, color: Colors.orange),
const SizedBox(height: 16),
const Text('Products unavailable offline'),
],
),
),
),
child: Scaffold(
appBar: AppBar(title: const Text('Products')),
body: const ProductsList(),
),
);
}
}
Default offline UI is shown when offlineBuilder is not provided.
Comparison #
| Type 1 — Snackbar | Type 2 — NetworkObserver |
Type 3 — NetworkAwareWidget |
|
|---|---|---|---|
| Scope | Per request | Whole app | Single page |
| UI | Snackbar / custom callback | Dialog or full page | Inline widget swap |
| Setup | Add to dio.interceptors |
Wrap MaterialApp once |
Wrap each page |
| Auto-recover | — | ✅ | ✅ |
| Use when | Custom feedback per request | Global fallback for all screens | Page-specific offline content |
They can be used together — NetworkObserver as global fallback, NetworkAwareWidget for pages that need a custom offline experience.
Advanced #
Custom connectivity check URIs #
By default, the package uses built-in URIs from internet_connection_checker_plus.
Override them when your app runs behind a firewall or you want to verify your own backend:
NetworkInterceptor(
customCheckOptions: [
InternetCheckOption(uri: Uri.parse('https://api.yourapp.com/health')),
],
)
Pass an empty list or omit to use package defaults.
Disable pre-request or response checks #
NetworkInterceptor(
checkBeforeRequest: false, // skip check before sending
checkOnResponse: false, // skip check when response arrives
)
Inject a custom ConnectivityService (for testing) #
NetworkInterceptor(
connectivityService: MockConnectivityService(),
)
API Reference #
NetworkInterceptor #
| Parameter | Type | Default | Description |
|---|---|---|---|
checkBeforeRequest |
bool |
true |
Check internet before sending request |
checkOnResponse |
bool |
true |
Check internet when response arrives |
onNoInternet |
Future<void> Function(RequestOptions)? |
null |
Called when no internet detected |
onNetworkError |
void Function(NetworkException)? |
null |
Called for every mapped error |
customCheckOptions |
List<InternetCheckOption>? |
null |
Custom URIs for connectivity checks |
connectivityService |
ConnectivityService? |
null |
Custom service (useful for testing) |
NetworkObserver #
| Parameter | Type | Required | Description |
|---|---|---|---|
navigatorKey |
GlobalKey<NavigatorState> |
✅ | Must match MaterialApp.navigatorKey |
child |
Widget |
✅ | Typically MaterialApp |
dialogBuilder |
WidgetBuilder? |
— | Custom offline dialog |
pageBuilder |
WidgetBuilder? |
— | Full offline page (takes priority) |
connectivityService |
ConnectivityService? |
— | Custom service (useful for testing) |
NetworkAwareWidget #
| Parameter | Type | Required | Description |
|---|---|---|---|
child |
Widget |
✅ | Shown when online |
offlineBuilder |
WidgetBuilder? |
— | Shown when offline. Falls back to default UI |
connectivityService |
ConnectivityService? |
— | Custom service (useful for testing) |
NetworkException #
| Property | Type | Description |
|---|---|---|
type |
NetworkErrorType |
Category of error |
message |
String |
Human-readable description |
statusCode |
int? |
HTTP status — only set for serverError |
isNoInternet |
bool |
Shorthand for type == noInternet |
isTimeout |
bool |
Shorthand for type == timeout |
isServerError |
bool |
Shorthand for type == serverError |
NetworkErrorType #
| Value | Cause |
|---|---|
noInternet |
No active internet connection |
timeout |
Connect, send, or receive timeout |
serverError |
Non-2xx HTTP response |
cancelled |
Request cancelled via CancelToken |
unknown |
Unrecognized error |
Contributing #
Contributions are welcome! Feel free to open issues or submit a pull request. For significant changes, please open an issue first to discuss what you'd like to change.