← All docs

Monitor widget

Show live status for the monitors you choose inside your own product: a dashboard, an admin panel, a settings page, a footer. The widget is a web component that takes on your app's font and colours, and you can point it at your design tokens.

Create a widget

In the app, open Widgets and click New widget. Pick the monitors, give internal ones a public name, choose a layout and style, and watch the live preview. Then click Get code:

html
<script src="https://spotdowntime.com/widget.js" async></script>
<spot-downtime-status embed="emb_your_token"></spot-downtime-status>

The style you save is the default. Change it later in Spot Downtime and every embed updates within 30 seconds, with no redeploy.

Let your AI assistant add it

Using Claude Code, Cursor, GitHub Copilot or Windsurf? In Get code, open the AI assistant tab, say where the widget should go, and paste the prompt into your assistant with your app's project open. It loads the widget the right way for your framework, maps your design tokens onto it so it matches your UI and dark mode, and updates your Content Security Policy. The prompt looks like this:

prompt
Add the Spot Downtime monitor widget "Dashboard" to this web app, so its users see live service status, styled to look native to the app.

Widget
- Script (load once per page): <script src="https://spotdowntime.com/widget.js" async></script>
- Element: <spot-downtime-status embed="emb_your_token"></spot-downtime-status>
- The embed token is public and safe in source code. No API key is needed in the app.
- Optional attributes override the saved look: layout (card | list | bars | pill | inline), theme (auto | light | dark | inherit), accent, radius, density (comfortable | compact), font (inherit | system | mono), days (30 | 60 | 90), headless.
- Docs: https://spotdowntime.com/docs/monitor-widget

Steps
1. Placement: Put it here: the dashboard sidebar. Pick the layout to fit: list inside one of the app's existing card components, card on its own, bars for a dedicated status section, pill or inline in a footer or navbar.
2. Load the script once for the whole app, never on every render or route change:
   - Next.js: next/script in the root layout, strategy="afterInteractive".
   - React (Vite, CRA): index.html before </body>, or a component that appends the script once (check it isn't already there).
   - Vue / Nuxt: index.html or the head config; also mark it as a custom element: compilerOptions.isCustomElement = (tag) => tag === "spot-downtime-status".
   - Svelte / SvelteKit: app.html. Angular: index.html, and CUSTOM_ELEMENTS_SCHEMA where the element is used.
   - Server templates or plain HTML: the base layout.
3. Render <spot-downtime-status embed="emb_your_token"> where it belongs. Follow the project's conventions: in a component-based app, make a small SystemStatus component. In React with TypeScript, declare the element in JSX.IntrinsicElements (embed, layout, theme, accent, radius, density, font) so it type-checks.
4. Match the design system. Find the app's theme tokens: CSS variables (e.g. shadcn/ui --card, --border, --primary, --radius), the Tailwind theme, or a component library theme (MUI, Chakra, Mantine, Ant). In the global stylesheet, map them onto the widget's variables, using the app's variables rather than fixed colours so light and dark mode follow automatically:
     spot-downtime-status { --sd-bg; --sd-fg; --sd-muted; --sd-border; --sd-hover; --sd-accent; --sd-radius; --sd-font }
   Also available: --sd-up, --sd-down, --sd-warn, --sd-maint, --sd-idle, --sd-shadow, --sd-font-size, --sd-padding, --sd-bar-height. Inside an existing card, layout="list" with theme="inherit" usually fits with no mapping at all. For finer control, use ::part() (base, header, title, overall, list, row, dot, name, meta, latency, uptime, bars, bar, footer, link, button, panel).
   If I'd rather it were drawn with the app's own components, use headless JSON from https://spotdowntime.com/api/v1/public/embeds/emb_your_token instead (fields: overall, monitors[].name/status/uptime/uptime_24h/latency_ms/days), polling every 60 seconds at most.
5. If the app sets a Content-Security-Policy (headers, middleware, a meta tag, vercel.json, netlify.toml, _headers, nginx), add https://spotdowntime.com to script-src and connect-src. Loosen nothing else.
6. Don't add dependencies or change unrelated markup, styles or behaviour.
7. When done, list the files you changed and how to check it: open that page; the widget shows each monitor with a coloured dot and its status, and follows the app's theme.

Connected over MCP? If your assistant is connected to Spot Downtime (see MCP setup), skip the copying. Ask something like “add a status widget for our API monitors to the dashboard, matching our theme”. It creates the widget with create_widget, fetches the code and instructions with get_widget_code, and edits your project. API keys can create and change widgets, but not delete them or replace their code, since that would break live embeds.

Review the assistant's changes before you deploy, as you would any code change.

Layouts and attributes

Every attribute is optional and overrides the saved style for that one embed.

AttributeValues
layoutcard (a panel), list (rows only, for your own card), bars (daily uptime history), pill (a button that opens the list), inline (one line of text)
themeauto (follows the visitor's light/dark setting), light, dark, inherit (the surrounding text colour on a transparent background)
accentAny CSS colour, for links and focus rings
radiusCorner radius in px
densitycomfortable or compact
fontinherit (your app's font, the default), system or mono
days30, 60 or 90 days of bars, for the bars layout
refreshSeconds between updates, 30 or more (default 60)
headlessDraw nothing; listen for the sd-status event instead

One script tag works too, if you can't add elements: <script src="https://spotdowntime.com/widget.js" data-embed="emb_your_token" data-layout="pill" async></script>. Add data-target="#selector" to mount it somewhere else.

Match your design system

Set --sd-* CSS variables anywhere above the widget, even on :root. They take priority over the saved style, so the widget follows your light and dark themes on its own:

css
/* Point the widget at your design tokens (shadcn/ui shown; use your own). */
spot-downtime-status {
  --sd-bg: var(--card);
  --sd-fg: var(--card-foreground);
  --sd-muted: var(--muted-foreground);
  --sd-border: var(--border);
  --sd-hover: var(--muted);
  --sd-accent: var(--primary);
  --sd-radius: var(--radius);
  --sd-font: inherit;          /* or your font stack */
  /* Also: --sd-up --sd-down --sd-warn --sd-maint --sd-idle --sd-shadow
     --sd-font-size --sd-padding --sd-bar-height --sd-bar-empty --sd-pill-radius */
}

/* Style any piece with ::part() */
spot-downtime-status::part(row):hover { background: var(--muted); }
spot-downtime-status::part(title) { text-transform: uppercase; letter-spacing: .04em; }

Available parts: base header title overall list row dot name meta latency uptime bars bar footer link branding button panel.

React, Next.js, Vue and others

It's a standard custom element, so it works in any framework. In React or Next.js:

tsx
"use client";
import { useEffect } from "react";

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      "spot-downtime-status": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
        embed: string; layout?: string; theme?: string; accent?: string; radius?: number; density?: string; font?: string;
      };
    }
  }
}

export function SystemStatus(props: { layout?: "card" | "list" | "bars" | "pill" | "inline"; theme?: "auto" | "light" | "dark" | "inherit" }) {
  useEffect(() => {
    if (document.querySelector('script[src="https://spotdowntime.com/widget.js"]')) return;
    const s = document.createElement("script");
    s.src = "https://spotdowntime.com/widget.js";
    s.async = true;
    document.head.appendChild(s);
  }, []);
  return <spot-downtime-status embed="emb_your_token" {...props} />;
}

Vue, Svelte and Angular:

html
<!-- Load once, e.g. in index.html -->
<script src="https://spotdowntime.com/widget.js" async></script>

<!-- Then use it like any element -->
<spot-downtime-status embed="emb_your_token" layout="list" theme="inherit"></spot-downtime-status>

<!-- Vue: tell the compiler it's a custom element (vite.config):
  vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === "spot-downtime-status" } } })
  Angular: add CUSTOM_ELEMENTS_SCHEMA to the component's schemas. -->

Use your own components

Want it drawn entirely with your own components? Read the same data as JSON. It needs no key and allows any origin:

js
// The same data as JSON, readable from any origin. Updates every 30 seconds.
const res = await fetch("https://spotdowntime.com/api/v1/public/embeds/emb_your_token");
const { overall, monitors } = await res.json();
// overall: "operational" | "partial_outage" | "major_outage" | "maintenance"
// monitors: [{ name, status, uptime, uptime_24h, latency_ms?, last_checked_at, days: [{ date, uptime }] }]

// Or let the widget poll for you and render nothing:
// <spot-downtime-status embed="emb_your_token" headless></spot-downtime-status>
document.addEventListener("sd-status", (e) => render(e.detail));

In the browser, SpotDowntime.fetch("emb_your_token") (after loading widget.js) returns the same data and shares requests between widgets.

Content Security Policy

If your app sends a Content-Security-Policy header, allow spotdowntime.com:

http
Content-Security-Policy: script-src 'self' https://spotdowntime.com; connect-src 'self' https://spotdowntime.com

Headless use only needs connect-src.

What it shows

  • Names (or the public names you set), states, uptime and daily history. Never URLs, hosts or error details.
  • Response times only if you turn on Show response times.
  • The embed code is public, since it's in your page source. If it ends up somewhere you don't want, click Make new code: the old one stops working at once.
  • It draws in an isolated Shadow DOM, sets no cookies and collects nothing about your visitors.
  • The Free plan shows a small “by Spot Downtime” link; paid plans don't.

Troubleshooting

ProblemFix
Nothing appearsCheck the browser console. Usually the embed code was replaced or deleted, or your Content Security Policy blocks the script.
Wrong font or coloursWith theme="inherit" and font="inherit" it copies the element around it. Set --sd-* variables to choose exactly.
The pill's list is cut offA parent element has overflow: hidden. Give the widget more room, or use the card or list layout.
Want a whole public page instead? See the status page widget.

Something missing or unclear? Tell us.