Feedback

ConnectionIndicator

Small standalone status pill for a live connection, distinguishing connecting, live, reconnecting, polling, stale, and closed states through icon and text rather than color alone.

import { ConnectionIndicator } from '@lostgradient/cinder/connection-indicator';
connectionstatusrealtime
01

Overview

Small standalone status pill for a live connection. Renders one of six states — connecting, live, reconnecting, polling, stale, closed — as an icon plus a text label, so status is never conveyed by color alone.

live shows a small pulsing dot (a static dot under prefers-reduced-motion: reduce). polling is deliberately quieter than live: no motion, a lighter label weight, and its own icon, so it can't be mistaken for push. reconnecting accepts an optional attempt snippet for showing a retry count like "attempt 3 of 5".

Use ConnectionIndicator for a compact, self-contained pill that reports transport health. Use StatusDot for annotating a static entity's state (a row, a user, a deployment) instead of a live transport. Use EventStreamViewer for a full event log rather than a single status pill.

Usage

svelte 
<script lang="ts">
  import { ConnectionIndicator } from '@lostgradient/cinder/connection-indicator';
</script>

<ConnectionIndicator status="live" />
<ConnectionIndicator status="polling" />
<ConnectionIndicator status="closed" />

With an attempt count

svelte 
<script lang="ts">
  import { ConnectionIndicator } from '@lostgradient/cinder/connection-indicator';
</script>

<ConnectionIndicator status="reconnecting">
  {#snippet attempt()}
    attempt 3 of 5
  {/snippet}
</ConnectionIndicator>

With a label override

svelte 
<ConnectionIndicator status="stale" label="Data may be out of date" />
Live preview
02

When to use

Use when
  • Surfacing the transport-level health of a websocket, SSE stream, or polling loop as a compact, self-contained pill.
  • Distinguishing push (`live`) from interval polling (`polling`) so operators don't mistake one for the other.
Avoid when
  • Annotating a static entity's state (a row, a user, a deployment) rather than a live transport — use status-dot instead. Use Status dot instead
  • Rendering a full event log with per-event connection transitions — use event-stream-viewer instead. Use Event stream viewer instead
03

Examples

Basic connection indicator

A live connection pill with its default icon and label.

Polling vs live

Polling reads quieter and different from live through icon, motion, and font-weight — not color alone.

Reconnecting with attempt count

The reconnecting state showing a retry attempt via the attempt snippet.

All connection states

Each of the six states with its own icon and text label. Colors come from shared semantic tokens, so some states intentionally share a tone (e.g. connecting/reconnecting) — the icon and text carry the distinction, never color alone.

04

Props

Props for connection-indicator
Name Type Default Required Bindable Description
status 'connecting''live''reconnecting''polling''stale''closed' req Current connection lifecycle state. Drives icon, text, and color via data-cinder-status.
label text Optional human label override. Replaces the default text for status (and the "Connection: …" accessible name).
attempt snippet Attempt-count content rendered next to the label when status is 'reconnecting', e.g. "attempt 3 of 5". Ignored for other states.
05

Accessibility

Status is conveyed by icon and text together, never color alone (WCAG 1.4.1); the live pulsing dot collapses to a static dot under prefers-reduced-motion.