@checkly/elements

Embeddable Checkly monitoring UI as framework-agnostic custom elements — status, uptime, stats and incidents that can be dropped into any page regardless of the framework around it.

Browser-only and ES-only: loaded by a <script type="module"> on your page, with no CommonJS build. lit and @lit/context are the only runtime dependencies, and a test keeps that list from growing.

Install

Prereleases are on npm under the pre tag; there is no stable release yet.

pnpm add @checkly/elements@pre

Each prerelease is named after the commit it was built from, so pin the exact version in a project that has to reproduce its builds. To work on both sides at once, build this checkout (pnpm install also builds dist/) and pnpm link /absolute/path/to/checkly-elements from the consumer.

Consuming from another repository covers the other routes in.

Each element is imported from its own entry point, and importing it is what registers the tag:

<script type="module">
  import '@checkly/elements/status-dot'
</script>

<checkly-status-dot status="failing" label="Checkout API"></checkly-status-dot>
<checkly-status-dot status="success" size="small"></checkly-status-dot>

What is here

The catalog contains 14 display elements, plus optional API adapters, an HTTP client, and two public-resource sources. Display elements render from plain view-model properties, so a host can compose a board from its own store.

| Path | Purpose | | --- | --- | | src/core | The base classes every element is built on: the token table, the four data states, the shadow/light-DOM machinery, the source channel. | | src/client | The HTTP transport, paging and visibility-aware polling used by source elements and server-side consumers. | | src/adapters | Pure mappings from dashboard and status-page wire responses onto the view-model the elements render. | | src/sources | Optional custom elements that fetch public dashboards or status pages and feed the rendering catalog beneath them. | | src/elements | The catalog. A file here is automatically an entry point, a size budget, and a subject of every conformance suite. | | themes/ | checkly.css, generated: switches the elements' light and dark mode with a .dark class, as Checkly's applications do. The product look itself is the elements' default. | | demo/ | A review hub for responsive states, themes, and live public-resource fetching. | | scripts/ | The build's supporting cast: generated style docs, size budgets, the self-documenting check. |

Fetching Checkly data

The rendering catalog and fetching client are separate entry points. A page that already owns its data therefore downloads no HTTP or polling code:

import { ChecklyClient } from '@checkly/elements/client'

const client = ChecklyClient.forDashboard({ dashboardId: 'my-dashboard' })
const statuses = await client.listCheckStatuses()

forDashboard and forStatusPage use the corresponding published-resource APIs. forApi is for server-side code and requires an account API key plus its account id.

Consumers that already perform their own requests can import the same mapping functions without taking the client or any elements:

import { adaptChecks } from '@checkly/elements/adapters'

For a framework-free public dashboard, import its source and wrap the elements that should receive its data:

<script type="module">
  import '@checkly/elements/dashboard-source'
  import '@checkly/elements/check-list'
</script>

<checkly-dashboard-source dashboard-id="my-dashboard">
  <checkly-check-list></checkly-check-list>
</checkly-dashboard-source>

Status pages use @checkly/elements/status-page-source and require version="v2" or version="v3". These source elements intentionally support public resources only; protected resources need the separately designed authentication bridge.

The status-page source feeds nested service uptime, incident banners/lists and maintenance lists. Select uptime with service-id, and use history on an incident list to show its archive. Your page owns the layout, service headings and branding; the source owns requests and the API-specific mapping.

Scoped account-data pilot

Author-composed pages can also use the experimental /v1/embed-tokens and /v1/elements-data endpoints, behind the ELEMENTS_EMBED account flag. A server-held API credential mints a short-lived JWT for explicit check IDs; the browser fetches once and passes the snapshot through adaptElementsSnapshot to the pure elements. No polling, dashboard or status-page dependency is needed.

The showcase repository holds a working example: a local server that keeps the key, the handshake, and the probes that prove it fails closed.

API keys are server side only

An account API key can read the account and does not belong in browser code. ChecklyClient.forApi() refuses cu_ and sv_ keys in a browser unless the caller explicitly sets unsafeAllowBrowserApiKey; that escape hatch still logs the risk. Prefer a published dashboard or status page, or proxy the specific account data through a backend that keeps the key private.

Develop

pnpm install         # also builds, via prepare
pnpm demo            # the demo pages on :5173
pnpm test            # build, unit specs, hygiene
pnpm test:browser    # real Chromium, via Playwright

The browser runner needs a binary the first time:

pnpm exec playwright install chromium

Every command, and what each one is for, is in docs/development.md.

Documentation

| | | | --- | --- | | Using the elements | The elements themselves: what they take, the four states every one of them has, and how a source feeds them. | | Restyling | Making these look like your product: tokens, parts, slots, and dropping the shadow boundary. Includes the generated table of every token, part and slot the catalog declares. | | Consuming from another repository | The three ways in — published to npm, pinned to a commit, or linked locally — and which to reach for. | | Development | Commands, the two test runners, the demo pages, entry points, size budgets. | | Publishing | How a release runs, and what has to be true before the first one. | | AGENTS.md | Instructions for coding agents working in this repository. |

License

MIT.