Flutter Integration

Network Status Widgets

NetworkStatusBuilder and NetworkStatusIndicator: reactive widgets for displaying offline state in Flutter apps.

NetworkStatusBuilder and NetworkStatusIndicator are two Flutter widgets that subscribe to the ConnectivityManager exposed by the nearest QoraScope and rebuild whenever the NetworkStatus changes.

Requirements

A QoraScope with a ConnectivityManager must be an ancestor. Without one, both widgets emit NetworkStatus.unknown and never update.

lib/main.dart

QoraScope(
  client: client,
  connectivityManager: FlutterConnectivityManager(), // required
  child: const MyApp(),
)

`NetworkStatusIndicator`

The high-level widget. Wraps your app (or a sub-tree) and overlays an offline banner when NetworkStatus.offline is detected.

Default banner

lib/main.dart

QoraScope(
  client: client,
  connectivityManager: FlutterConnectivityManager(),
  child: NetworkStatusIndicator(
    child: const MyApp(),
  ),
)

Renders a thin semi-transparent dark bar at the bottom of the screen with a wifi-off icon and "Offline mode" text. No Material dependency: uses only flutter/widgets.dart.

Custom offline banner

Override the offline UI with offlineBanner:

lib/main.dart

NetworkStatusIndicator(
  offlineBanner: (context) => Container(
    color: Colors.orange.shade800,
    padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
    child: const Row(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Icon(Icons.wifi_off, color: Colors.white, size: 16),
        SizedBox(width: 8),
        Text('No connection', style: TextStyle(color: Colors.white)),
      ],
    ),
  ),
  child: const MyApp(),
)

offlineBanner is ignored when a custom builder is provided.

Full builder control

Use builder when you need to react to every NetworkStatus value: including online and unknown:

lib/main.dart

NetworkStatusIndicator(
  builder: (context, status, child) {
    return Stack(
      children: [
        child!,
        if (status == NetworkStatus.offline)
          const Positioned(
            bottom: 0, left: 0, right: 0,
            child: MyOfflineBanner(),
          ),
        if (status == NetworkStatus.unknown)
          const Positioned(
            bottom: 0, left: 0, right: 0,
            child: MyCheckingBanner(),
          ),
      ],
    );
  },
  child: const MyApp(),
)

Props

Prop	Type	Default	Description
`child`	`Widget`	required	The main content of the app.
`builder`	`Widget Function(BuildContext, NetworkStatus, Widget?)?`	`null`	Full control builder. When set, `offlineBanner` is ignored.
`offlineBanner`	`Widget Function(BuildContext)?`	`null`	Custom widget shown at the bottom when offline.

`NetworkStatusBuilder`

The low-level widget. Subscribes to the ConnectivityManager stream and calls builder on every NetworkStatus transition. Use this when you need fine-grained control over how each status is rendered.

Basic usage

lib/ui/widgets/offline_banner.dart

NetworkStatusBuilder(
  builder: (context, status, child) {
    return status == NetworkStatus.offline
        ? const MyOfflineBanner()
        : const SizedBox.shrink();
  },
)

With child optimisation

Pass an expensive sub-tree as child to avoid rebuilding it on every status change:

lib/ui/screens/home_screen.dart

NetworkStatusBuilder(
  builder: (context, status, child) {
    return Column(
      children: [
        if (status == NetworkStatus.offline) const OfflineBanner(),
        Expanded(child: child!),
      ],
    );
  },
  child: const ExpensiveContentTree(),
)

The framework reuses child across builder calls: only the wrapper rebuilds.

Reading the current status imperatively

lib/ui/offline_badge.dart

final manager = QoraScope.connectivityManagerOf(context);
final status = manager?.currentStatus ?? NetworkStatus.unknown;

Props

Prop	Type	Default	Description
`builder`	`Widget Function(BuildContext, NetworkStatus, Widget?)`	required	Builds the widget tree for the given `NetworkStatus`.
`child`	`Widget?`	`null`	Optional child passed unchanged to `builder`.

`NetworkStatus` values

Value	Meaning
`NetworkStatus.online`	Device has at least one active network interface.
`NetworkStatus.offline`	All network interfaces are down.
`NetworkStatus.unknown`	No `ConnectivityManager` is registered, or status has not yet been determined.

NetworkStatus reflects interface availability, not actual internet reachability. A device connected to a router with no WAN access will report online. For reachability validation, add a custom health-check in your ConnectivityManager implementation.

Recommended placement

Place NetworkStatusIndicator just inside QoraScope, wrapping the entire app. This ensures the banner is always visible regardless of which route is active:

lib/main.dart

runApp(
  QoraScope(
    client: client,
    connectivityManager: FlutterConnectivityManager(),
    child: NetworkStatusIndicator(
      child: MaterialApp(
        home: const HomeScreen(),
      ),
    ),
  ),
);

Next Steps

Network Aware Guide: Full offline-first setup walkthrough
QoraScope: Wiring FlutterConnectivityManager into the widget tree
QoraBuilder: Using FetchStatus.paused for per-widget offline indicators

Edit this pageorReport an issue

Hooks (flutter_hooks)

Use useQuery, useMutation, useInfiniteQuery, useIsFetching and useIsMutating with flutter_hooks for a concise, composable API.

Best Practices

Patterns and conventions for building reliable Flutter apps with Qora: keys, query placement, mutation wiring, and performance.