@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 15 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 screenshot suite, the demo pages, entry points, size budgets. |
| Publishing | How a prerelease and a release run, what the registry's tags mean, and what has to be true before the first stable version. |
| AGENTS.md | Instructions for coding agents working in this repository. |
License
MIT.