Widget
Embed a live status widget on any page with a JavaScript snippet.
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.
- Open the dashboard you want to embed and go to the Widget tab.
- Toggle Enable embeddable widget on.
- Copy the embed code from the Embed code section.
- Paste the
<script>tag anywhere in your HTML, typically just before</body>.
<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).
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:
<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:
<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. 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 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.