network

Track connectivity and connection quality.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useNetwork, useOnline } from "@vizejs/composable/network";

Try it

Keep a local guide draft usable when the browser goes offline

Observe actual browser connectivity and optional connection estimates without confusing an online flag with successful service access.

Open the interactive example

What to observe: Edit Local guide draft, then use the browser's offline switch. Browser status follows the native online/offline event and records its actual event time. The draft and Review local draft remain usable while offline. Reconnect to see the online event. Unknown connection estimates stay explicitly unknown.

useNetwork uses the actual window/navigator, native online/offline events, and navigator.connection where supported. isSupported describes the optional Network Information API, not whether online/offline observation works. The browser's onLine flag cannot certify service reachability; downlink, class, and round-trip values are estimates. Event timestamps start null and update only on actual events. SSR starts with its default true fallback and null quality measurements, then component mounting reads the browser. Native input and the local review counter belong to the example and send no request or save. Scope disposal removes all window/connection listeners. No network host is injected.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref, useId } from "vue";
import { useNetwork } from "@vizejs/composable/network";

const draftId = useId();
const draft = ref("");
const reviews = ref(0);
const { isSupported, isOnline, onlineAt, offlineAt, effectiveType, downlink, rtt, saveData } =
  useNetwork();

function eventTime(value: number | null): string {
  return value === null ? "not observed" : new Date(value).toISOString();
}
</script>

<template>
  <div class="composable-example">
    <label :for="draftId">Local guide draft</label>
    <input :id="draftId" v-model="draft" />
    <button type="button" @click="() => (reviews += 1)">Review local draft</button>
    <p>Local review count: {{ reviews }}.</p>
    <output aria-live="polite">Browser status: {{ isOnline ? "online" : "offline" }}</output>
    <p v-if="!isOnline">The browser reports offline. Your local draft remains editable.</p>
    <dl>
      <dt>Last online event</dt>
      <dd>{{ eventTime(onlineAt) }}</dd>
      <dt>Last offline event</dt>
      <dd>{{ eventTime(offlineAt) }}</dd>
      <dt>Network Information API</dt>
      <dd>{{ isSupported ? "available" : "unavailable" }}</dd>
      <dt>Estimated connection class</dt>
      <dd>{{ effectiveType ?? "unknown" }}</dd>
      <dt>Estimated downlink</dt>
      <dd>{{ downlink === null ? "unknown" : `${downlink} Mbit/s` }}</dd>
      <dt>Estimated round trip</dt>
      <dd>{{ rtt === null ? "unknown" : `${rtt} ms` }}</dd>
      <dt>Reduced data requested</dt>
      <dd>{{ saveData ? "yes" : "no" }}</dd>
    </dl>
    <p>
      Use your browser's offline switch or change the actual connection to observe these flags and
      event times. Online status is the browser's report; it does not guarantee that a service is
      reachable. Connection estimates are optional and may be unknown. No request or draft save is
      sent here. Server rendering starts online with no observed event or quality measurements; the
      client reads the real browser after mounting.
    </p>
  </div>
</template>

Runtime contract

API

useNetwork

Track connectivity and connection quality. Listens for online/offline on the window and change on navigator.connection where available. Unknown or future enum values normalize to null so the public unions stay closed. Server renders report ssrOnline with every quality metric null. Inside a component the connection is read after mounting, so hydration renders the server values first. Listeners are removed with the owning reactive scope.

function useNetwork(options: UseNetworkOptions = {}): NetworkControls

useOnline

Track whether the browser reports being online. Shorthand for useNetwork(options).isOnline with the same SSR fallback and cleanup semantics.

function useOnline(options: UseNetworkOptions = {}): Readonly<Ref<boolean>>

Types

NetworkInformationLike

Subset of the (non-standard) NetworkInformation interface.

NetworkHost

Window-like capability observed by the network composables.

UseNetworkOptions

Options shared by useOnline and useNetwork.

NetworkControls

Reactive network state returned by useNetwork.