English | Русский: see docs EN • RU

Minimal, framework‑free Web Component for displaying service status via GET /health. Lightweight, accessible, themeable, and i18n‑friendly.

• Zero deps, ESM, tree‑shakable
• Three UI variants: dot • chip • badge
• Emits health-change and health-error
• Debounced visual updates, background optimizations
• A11y‑ready: role=status, aria-live=polite, forced‑colors support

Table of Contents

• Table of Contents
• Quick Start
• Install
• Usage
• Attributes and Properties
• Events
• Theming
• React Integration
• Backend and CORS
• Local Demo
• Browser Support
• License

Quick Start

Docs: EN • RU

Add the script and the element with your endpoint:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@worldhacker/service-health-badge/dist/service-health-badge.js"
></script>

<service-health-badge
  endpoint="https://api.example.com/health"
  variant="badge"
  degraded-threshold-ms="150"
></service-health-badge>

Install

Docs: EN • RU

• npm: npm i @worldhacker/service-health-badge
• pnpm: pnpm add @worldhacker/service-health-badge
• yarn: yarn add @worldhacker/service-health-badge

Import in your app:

import '@worldhacker/service-health-badge';

Via CDN (ESM):

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@worldhacker/service-health-badge/dist/service-health-badge.js"
></script>

Usage

Docs: EN • RU

Minimal example:

<service-health-badge endpoint="/health"></service-health-badge>

Full example with params and i18n:

<service-health-badge
  endpoint="/health"
  interval="10000"
  timeout="3000"
  variant="badge"
  degraded-threshold-ms="200"
  labels='{"ok":"OK","degraded":"Slow","down":"Down","unknown":"—","offline":"Offline"}'
></service-health-badge>

JS API (props/methods):

const el = document.querySelector('service-health-badge');
el.interval = 8000;
el.timeout = 2500;
el.showLatency = true;
el.degradedThresholdMs = 150;
el.labels = { degraded: 'Reduced' };
await el.refresh();

Attributes and Properties

Docs: EN • RU

• endpoint: string — GET /health endpoint (required to poll).
• interval: number (ms), default 10000 — polling period.
• timeout: number (ms), default 3000 — request timeout.
• labels: JSON, merged with defaults — localized labels.
• variant: dot | chip | badge (default badge).
• show-latency: set false to hide latency in badge.
• degraded-threshold-ms: number (ms). If base is ok and latency > threshold → render degraded.
• focusable: when present, element is keyboard focusable.
• dev-state: force a state for local dev (unknown|ok|degraded|down|offline).

Available statuses: unknown, ok, degraded, down, offline.

Methods:

• refresh(): Promise<boolean> — poll immediately.
• setState(status, latencyMs?) — set state manually (threshold still applies).

Events

Docs: EN • RU

• health-change — on effective status change. detail: { status, latencyMs, at }.
• health-error — on network/timeout/JSON error. detail: { error }.

Example:

<service-health-badge id="hb" endpoint="/health"></service-health-badge>
<script>
  const el = document.getElementById('hb');
  el.addEventListener('health-change', (e) => {
    const { status, latencyMs } = e.detail;
    console.log('status =', status, 'latency =', latencyMs);
  });
  el.addEventListener('health-error', (e) => console.warn('health-error:', e.detail.error));
  // document.getElementById('btn').onclick = () => el.refresh();
</script>

Theming

Docs: EN • RU • Variants EN • RU

CSS custom properties are supported (global or per element):

• --health-size: base font size (0.875rem)
• --health-radius: border radius (0.5rem)
• --health-color-fg: text color (currentColor)
• --health-chip-bg: chip/badge background (rgba(0,0,0,0.05))
• --health-bg-ok|degraded|down|unknown|offline: indicator colors
• --health-focus-ring: focus ring color (optional)

React Integration

Docs: EN • RU

Use the wrapper from examples/react/HealthBadge.tsx or create the element directly:

import React from 'react';
import '@worldhacker/service-health-badge';

export function HealthBadge(props: any) {
  return React.createElement('service-health-badge', props as any);
}

<HealthBadge endpoint="/health" variant="badge" degradedThresholdMs={150} />;

Backend and CORS

Docs: EN • RU

Component expects JSON from GET /health. Minimal:

{ "status": "ok", "timings": { "total_ms": 23 } }

Local Demo

• Start mock /health server: npm run mock → prints http://127.0.0.1:<port>
• Preview static demo: npm run preview → open /demo/index.html

The demo UI lets you switch server vs. local fetch stub.

Browser Support

• Modern browsers with Web Components (Custom Elements, Shadow DOM).
• Polyfills are not bundled. Add CE/Shadow DOM polyfills if you target very old browsers.

License

MIT © 2025 — see LICENSE.