# Widget

Embed a live status widget on any page with a JavaScript snippet.

Source: https://statusdashboard.com/docs/status-dashboards/widget

> This is a plan-gated feature. If it isn't available in your account, visit the [Billing](/docs/org-mgmt/billing) page or contact support to review your options.

The embeddable widget surfaces live status on your own site with a small JavaScript snippet. Visitors stay on your pages while still seeing current component health and active events.

***

## Adding the widget to your page
The embeddable widget lets you surface your status dashboard directly on any website or web application — without asking your users to visit a separate URL. When activated, StatusDashboard generates a JavaScript snippet you paste into your HTML. The script injects a lightweight UI that always reflects your live system status.

1. Open the dashboard you want to embed and go to the **Widget** tab.
2. Toggle **Enable embeddable widget** on.
3. Copy the embed code from the **Embed code** section.
4. Paste the `<script>` tag anywhere in your HTML, typically just before `</body>`.

```html
<script
  src="https://api.statusdashboard.com/dashboard/widget/get.js?domain=mycompany.statusdashboard.io"
  async
></script>
```

The `domain` parameter in the script tag is set automatically based on your dashboard configuration — it uses your **custom domain** if one is active, or your **subdomain URL** (e.g. `mycompany.statusdashboard.io`) otherwise. Always copy the embed code directly from the Widget tab rather than writing it by hand.

> If you change your dashboard's subdomain or activate a custom domain, the embed code will change. Any previously deployed `<script>` tag pointing to the old domain will silently stop loading. Copy the updated embed code from the Widget tab and replace it on your site.

> **Propagation timing**
>   * **Configuration and theme changes** (colors, title, mode, component filter) are reflected for visitors within **5 minutes** of saving.
>   * **Live status data** (component statuses, active incidents, maintenance windows) refreshes automatically on each polling cycle — every 60 seconds by default, configurable up to 1 hour (see [Polling interval](#polling-interval)).

## Widget modes
Choose how the widget renders on your page:

| Mode      | Behaviour                                                                                                                                                                                                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Badge** | Fixed floating pill in the bottom-right corner. When all systems are operational, the closed pill shows your custom title. During an active incident or maintenance window, it shows live overall status instead. Activate it (click, Enter, or Space) to open a popover with the component list and a **View status page** link. Escape or a click outside closes it. |
| **Panel** | Inline panel rendered inside a target element you designate with `data-sd-widget` on a page element. Shows your custom title, overall status, component list, and **View status page** link.                                                                                                                                                                           |
| **Both**  | Always shows the floating badge. Also renders the inline panel when a `data-sd-widget` target is present.                                                                                                                                                                                                                                                              |

### Using panel mode
Add a target element to your HTML where you want the panel to appear:

```html
<div data-sd-widget></div>
```

The widget will populate that element with the status panel at runtime. The panel fills 100% of its container's width, so you can control the size by wrapping it:

```html
<div style="max-width: 400px;">
  <div data-sd-widget></div>
</div>
```

Any CSS class, grid column, or sidebar container works the same way.

## Display options
| Option           | Description                                                                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Custom title** | Overrides the default title ("System Status") shown in the panel and popover header. When all systems are operational, the closed badge also uses this title. Max 80 characters. |

The widget always shows each included component's current status and an overall status summary in the panel or popover header. A **View status page** footer link is always present.

## Component filter
By default the widget surfaces all components on your dashboard. To show only a subset — for example, only the components relevant to the page your customers are on — select specific components in the **Component filter** section.

When one or more components are selected, the widget status endpoint only returns data for those components. Overall status is derived from that same filtered set.

## Polling interval
The widget re-fetches live status on a configurable interval. Defaults to **60 seconds**.

| Setting | Range                 |
| ------- | --------------------- |
| Minimum | 30 seconds            |
| Maximum | 3600 seconds (1 hour) |

Leave the field blank to use the default.

## Theme
The **Theme** section lets you customize three colors used by the widget:

| Field                | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| **Primary color**    | Accent color applied to the widget border and header stripe. |
| **Background color** | Background of the badge pill, popover, and panel.            |
| **Text color**       | Body text color throughout the widget.                       |

All values are 6-digit hex colors (e.g. `#2d7a7b`). Click the color swatch to open a color picker, or type a hex value directly.

## Access control
The widget status endpoint (`/dashboard/widget/status`) respects your dashboard's **IP allowlist** if one is configured. Visitors outside the allowlist receive a `403` response and the widget will show an access-restricted state.

The widget does **not** participate in [SSO](/docs/status-dashboards/sso/overview). Even when SSO protects the main status dashboard page, the widget remains publicly accessible to anyone whose IP passes the allowlist (or to everyone if no allowlist is configured). Do not embed the widget on public pages if you intend the dashboard to be fully private.

See [SSO overview](/docs/status-dashboards/sso/overview) for how dashboard sign-in and the widget interact.

## Security
The widget script and status API are served with `Access-Control-Allow-Origin: *` to allow cross-origin embedding. No authentication credentials are sent to or required by these endpoints.

The widget script is a plain vanilla JavaScript IIFE with no external dependencies. It injects scoped CSS to avoid conflicts with your page styles.