> For the complete documentation index, see [llms.txt](https://docs.statuspal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.statuspal.io/next/status-pages/embed-a-status-widget.md).

# Embed a status widget

Add a small script to your website to show visitors a live banner during incidents and maintenance, plus an optional status badge, both fed by your status page.

The status widget puts your status page's live status directly on your own website, without sending visitors away to check it.

## What the widget adds to your site

The widget is a small script that reads your status page's current state and renders two optional pieces on top of your own site:

* A floating **banner** that appears automatically while an incident or maintenance is ongoing, and disappears once it is resolved.
* An inline **badge** that you place anywhere in your own markup, showing the page's status at a glance.

Both pull their data from your status page, so there is nothing to keep in sync. You turn each one on or off, and configure how it looks, entirely from the snippet described below.

## Add the script to your website

<figure><img src="https://4089725725-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQG79S8GZWmqk3Plak6MO%2Fuploads%2Fgit-blob-2cc13f829b39b41585c978f6b026aa3e356e9f5d%2Fwidget-settings-snippet.png?alt=media" alt="The Embed your Status Widget settings page for Acme, showing the JavaScript snippet with StatusPalNextWidgetConfig options for origin, theme, banner, and badge"><figcaption></figcaption></figure>

Open your status page's **Settings → Developers**. This area is available to members and admins. The page shows a ready-to-copy snippet:

```html
<script>
  window.StatusPalNextWidgetConfig = {
    origin: 'https://status.acme.com',
    theme: 'auto',
    banner: {
      enabled: true,
      position: 'bottom-right',
      theme: 'auto'
    },
    badge: {
      enabled: true,
      selector: '.statuspal-next-badge-container',
      placement: 'right',
      theme: 'auto'
    }
  };
</script>
<script src="https://widget.next.statuspal.io"></script>
```

Copy it as shown, with your own status page already filled in as `origin`, and paste it before the closing `</body>` tag of every page you want the widget to appear on. The `origin` setting is what points the widget at your status page; StatusPal Next fills it in for you with your page's address, whether that is your subdomain or a custom domain you have set up. See [custom domains](/next/status-pages/custom-domains.md) if you serve your status page at your own address.

## Configure the banner

While an incident or maintenance is ongoing on your status page, the banner appears in a corner of your site with the notice title, the affected services, its timing, and a link to the latest updates. Visitors can dismiss it with the cross.

<figure><img src="https://4089725725-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQG79S8GZWmqk3Plak6MO%2Fuploads%2Fgit-blob-875a891005ebaff99267a8c40e31707708f6ed4f%2Fwidget-banner.png?alt=media" alt="The status widget banner in the bottom-right corner of a website, showing a maintenance titled Database upgrade in the US region, the affected service Background jobs (US), the start time and duration, a View latest updates link, and a close button"><figcaption></figcaption></figure>

The `banner` object controls it:

| Option     | Values                                                 | Default                    |
| ---------- | ------------------------------------------------------ | -------------------------- |
| `enabled`  | `true`, `false`                                        | `true`                     |
| `position` | `bottom-right`, `bottom-left`, `top-right`, `top-left` | `bottom-right`             |
| `theme`    | `auto`, `light`, `dark`                                | the global `theme` setting |

Set `enabled` to `false` if you only want the badge. `position` chooses which corner of the screen the banner appears in. The banner only shows up while an incident or maintenance is ongoing on your status page and goes away once it is resolved, so most sites can leave it enabled with no further attention.

## Configure the badge

<figure><img src="https://4089725725-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQG79S8GZWmqk3Plak6MO%2Fuploads%2Fgit-blob-f0422ba5b0e345f015ec562d59552f6b14e30696%2Fwidget-badge-preview.png?alt=media" alt="The Demo preview of the badge section on the widget settings page, showing a pill-shaped Status badge with a green status indicator"><figcaption></figcaption></figure>

The badge does not float on its own. You add an anchor element to your own page wherever you want it to appear, matching the selector configured in the snippet:

```html
<!-- Make sure to match the configured badge selector -->
<a
  href="https://status.acme.com"
  class="statuspal-next-badge-container"
  target="_blank"
  >Status</a
>
```

The `badge` object controls how it behaves:

| Option      | Values                           | Default                           |
| ----------- | -------------------------------- | --------------------------------- |
| `enabled`   | `true`, `false`                  | `false`                           |
| `selector`  | any CSS selector                 | `.statuspal-next-badge-container` |
| `placement` | `right`, `left`, `top`, `bottom` | `right`                           |
| `theme`     | `auto`, `light`, `dark`          | the global `theme` setting        |

`selector` must match the class on the anchor element you added, so the widget knows where to render the status indicator. `placement` positions the indicator relative to your anchor's content. The widget only supplies the status indicator itself; the link's text, shape, and colors are your own HTML and CSS, so you can style it to match your site, as in the pill-shaped example above.

## Theme and appearance

The top-level `theme` setting is the widget's global theme: `auto`, `light`, or `dark`. `auto` follows the visitor's own dark mode preference rather than a fixed choice.

The `banner.theme` and `badge.theme` settings default to that global theme but can be overridden independently, so you could, for example, run the whole widget in `auto` while pinning the badge to `light` if that is what fits the spot on your page where you placed it. Beyond theme, the badge's appearance is entirely up to your own CSS on the anchor element; the banner's layout is fixed but respects the position and theme you set.