AddThisFeature

Connection Status Indicator

Tell people the app lost the server before their next click fails.

moderate Security & Reliability

What it adds

A persistent indicator that reports the app's real connectivity to the backend, and what the user can do about it.

What your agent is told to do

5
  1. 1

    Derive connection state from the outcome of real requests — timeouts, network errors, repeated failures — not from a browser flag.

  2. 2

    Distinguish at least four states: device offline, server unreachable, realtime channel dropped, and session expired. Each gets different copy, because each has a different fix.

  3. 3

    Show a reconnect or retry action on the indicator, and reconnect automatically with backoff in the background.

  4. 4

    Clear the indicator only after a successful request, not after a single successful ping to something unrelated.

  5. 5

    Do NOT trust navigator.onLine as the source of truth. It reports whether a network interface exists, which is true on captive-portal wifi, on a VPN that has dropped, and when your own API is down.

Edge cases it handles

6
  • Require two or three consecutive failures before showing the banner, so a single dropped request does not flash a scary message.
  • Backoff must be capped and jittered, or every client reconnects at the same instant and finishes the server off.
  • A 401 after reconnect is a session problem, not a network problem — route the user to sign in rather than retrying forever.
  • Degraded is a real state: requests succeeding slowly deserve a quieter message than requests failing.
  • The indicator must not cover a fixed bottom nav, a toast region, or the primary action on mobile.
  • Announce state changes to assistive technology once, not on every retry attempt.

Definition of done

8
  • Connection state is computed from actual request outcomes.
  • Offline, server-unreachable, realtime-dropped, and session-expired are shown as distinct states with distinct copy.
  • Brief network blips do not cause the indicator to flicker.
  • Reconnection is automatic with capped, jittered backoff, and a manual retry is available.
  • The indicator never obstructs navigation or primary actions.
  • State changes are announced once via an aria-live region.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.