> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://statpad.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server.

# Elements

> Reference for the scoreboard and scores elements, with attributes and defaults, slate dates, theming with attributes and CSS custom properties, events, widget states, browser support and React and Vue usage.

Both elements take their inputs as HTML attributes only. A value an element doesn't recognise falls back to the default, so a typo changes how a widget looks but doesn't break it.

## The key

The loader's `data-key` sets the key for every widget on the page:

```html
<script type="module" src="https://embed.statpad.dev/v1/embed.js" data-key="statpad_pk_..."></script>
```

A widget can use a different key with its own `data-key` or `key` attribute. When both are set, `data-key` wins. Use one loader per page: if several `embed.js` tags carry a `data-key`, the first one's key applies.

## `<statpad-scoreboard>`

One game.

```html
<statpad-scoreboard league="nfl" game="GAME_ID" variant="auto" theme="auto" surface="card"></statpad-scoreboard>
```

| Attribute         | Values                                   | Default                 |
| ----------------- | ---------------------------------------- | ----------------------- |
| `league`          | A league alias, such as `nfl` or `ncaab` | Required                |
| `game`            | The game's id, as in the REST API        | Required                |
| `variant`         | `auto`, `compact` or `expanded`          | `auto`                  |
| `theme`           | `auto`, `light` or `dark`                | `auto`                  |
| `accent`          | A hex colour, `#RGB` or `#RRGGBB`        | `#2F5BEA`               |
| `surface`         | `card` or `flush`                        | `card`                  |
| `data-key`, `key` | An embed key                             | The loader's `data-key` |

* **`compact`** is one row per team with its score, plus the game's status and, during play, the down and distance or which team is in the bonus.
* **`expanded`** adds each team's full name and timeouts, a countdown before the game, the red zone during a football game, the last play while the game is live or at a break, and the score by period.
* **`auto`** is compact in a container narrower than 380px and expanded from 380px up. It switches when the container resizes.

Without a valid `league`, `game` and key, the scoreboard shows **Widget not set up**.

## `<statpad-scores>`

A league's games for a day or a week.

```html
<statpad-scores league="ncaaf" date="week" layout="list" max="16"></statpad-scores>
```

| Attribute         | Values                                   | Default                                                      |
| ----------------- | ---------------------------------------- | ------------------------------------------------------------ |
| `league`          | A league alias                           | Required                                                     |
| `date`            | `today`, `week` or a day as `YYYY-MM-DD` | `week` for `nfl` and `ncaaf`, `today` for every other league |
| `layout`          | `list` or `strip`                        | `list`                                                       |
| `max`             | The most games to show, 1 to 100         | 12 for a day, 16 for a week                                  |
| `theme`           | `auto`, `light` or `dark`                | `auto`                                                       |
| `accent`          | A hex colour, `#RGB` or `#RRGGBB`        | `#2F5BEA`                                                    |
| `surface`         | `card` or `flush`                        | `card`                                                       |
| `data-key`, `key` | An embed key                             | The loader's `data-key`                                      |

A `list` is a column of rows. A `strip` is a single row of games, for the top of a page. A `max` above 100 shows 100.

Each row in a list is a button. Clicking a row, or pressing Enter or Space on it, fires [`statpad-select`](#events). The widget itself does nothing else, so you decide what a row opens.

### Dates

| `date`       | The games it shows                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `today`      | One US Eastern calendar day, midnight to midnight. It moves on to the next day at 05:00 Eastern, not at midnight, so a game that kicks off at 10:30 pm and runs past midnight stays on that day's list through the night. |
| `week`       | Tuesday 05:00 to the next Tuesday 05:00, US Eastern. That holds one football week, Thursday night through Monday night. Any league can use it.                                                                            |
| `YYYY-MM-DD` | That US Eastern calendar day, midnight to midnight, at any hour.                                                                                                                                                          |

Football defaults to `week` because a football slate is a week. Every other league defaults to `today`.

A game scheduled between midnight and 05:00 Eastern, such as a late kickoff in Hawaii, belongs to the calendar day it starts on. Until 05:00, `today` still shows the day before, so it shows that game only from 05:00, usually after it has ended. Its `YYYY-MM-DD` always includes it, and so does a `week`. Because a week starts at 05:00 on Tuesday, a game between midnight and 05:00 on a Tuesday is in the week that ends that morning, not the one that starts.

A day can be any date from 2026-08-01, when the earliest seasons Statpad holds begin, to 14 days after today. A day outside that range shows **Widget not set up**. A past day works, so a recap post can pin `date="2026-11-09"` and keep showing that day's finals.

The header shows the league and the day. For a week, it shows the week's label, such as **Week 11**, when every game in it is in the same regular-season week, and the date range otherwise. A week with no games reads **No NFL games this week**.

### Order and `max`

A list puts live games first. In a week, the live games sit under **Live** and the rest under a heading for each day, in the reader's time zone. A game still to come shows only its time and time zone under its day's heading.

When the window has more games than `max`, the list keeps the live games, then the games kicking off nearest to now, before or after. A college football Saturday therefore shows the games in progress and the next kickoffs, not the first 16 of the week.

### Team names

Compact scoreboards and scores lists name a college team (`ncaaf`, `ncaab`) by its school, such as **Alabama**, because mascots repeat across schools. They name a pro team by its team name, such as **Bills**. The expanded scoreboard shows both.

Teams are drawn as a helmet in the team's colours for football and a disc for basketball. Widgets never show team logos.

## Theming

Three attributes set the look:

* **`theme`**: `light`, `dark`, or `auto` to follow the reader's system setting.
* **`accent`**: the colour of live dots, highlights and the moment a score changes.
* **`surface`**: `card` has a background, a border and rounded corners. `flush` has a transparent background and a rule across the top, to sit inside your own layout.

Four CSS custom properties fine-tune it. Set them on the element or on any element that contains it:

| Property                | What it sets                                             | Default                                                    |
| ----------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| `--statpad-accent`      | The accent colour, when the `accent` attribute isn't set | `#2F5BEA`                                                  |
| `--statpad-font-family` | The font                                                 | Your page's font, then the system font                     |
| `--statpad-radius`      | The corner radius of a `card`                            | `14px`                                                     |
| `--statpad-surface`     | The background colour                                    | White in light, `#111112` in dark, transparent for `flush` |

```css
statpad-scoreboard,
statpad-scores {
  --statpad-accent: #c8102e;
  --statpad-font-family: "Inter", sans-serif;
  --statpad-radius: 8px;
}
```

Write colours as hex, `#RGB` or `#RRGGBB`. The widget works out text contrast from them, and it can't from any other form:

* An `accent` or `--statpad-accent` that isn't hex is ignored, and the default accent applies.
* A `--statpad-surface` that isn't hex still paints the background, but the widget checks text contrast against its default surface instead.

An accent with less than 3:1 contrast against the surface is darkened in light theme, or lightened in dark theme, until it reaches 3:1. So a pale brand colour still reads.

The widgets draw inside a shadow root, so the rest of your page's CSS doesn't reach inside them. They load no web fonts, set no cookies and use no storage. A change shows as a short flash of the accent. Readers who ask for reduced motion see the colour change without the motion.

## Events

All four events bubble, cross the shadow root, and are `CustomEvent`s with the payload in `detail`. None can be cancelled.

| Event            | When                                                                                                                                                                                                     | `detail`                     |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `statpad-ready`  | The first data arrives                                                                                                                                                                                   | The same as `statpad-update` |
| `statpad-update` | Anything in its `detail` changes: the state, a score, or a scoreboard's period or clock. That includes moves to reconnecting or unavailable and back. A check that changes none of them doesn't fire it. | See below                    |
| `statpad-error`  | A request fails with a new code                                                                                                                                                                          | `{ code, state }`            |
| `statpad-select` | A reader picks a row in `<statpad-scores>`                                                                                                                                                               | `{ game, league, state }`    |

These examples use the recorded Bills at Vikings game from [Sample responses](/docs/replay). Its id belongs to the sample data, so it won't load in a widget. A scoreboard's `statpad-update`, with 7:02 left in the fourth quarter:

```json
{
  "state": "live",
  "game": "01a1d60f-67be-7bdd-83f4-53286521d9bb",
  "home": { "abbr": "MIN", "score": 6 },
  "away": { "abbr": "BUF", "score": 13 },
  "period": "Q4",
  "clock": "7:02"
}
```

A scores list's `statpad-update` names the window's first day and every game in it:

```json
{
  "state": "live",
  "date": "2026-11-09",
  "games": [
    {
      "game": "01a1d60f-67be-7bdd-83f4-53286521d9bb",
      "state": "live",
      "home": { "abbr": "MIN", "score": 6 },
      "away": { "abbr": "BUF", "score": 13 }
    }
  ]
}
```

`state` is the widget's [state](#states-and-messages). A list's state is that of its most active game: live, then break, pregame, final and off. Scores are `null` before a game starts.

`statpad-error`'s `code` is one of the [error codes](/docs/embeds/origins#error-codes), `network` when no answer arrived within 10 seconds, or `invalid_response` when the answer couldn't be read. It fires once per new code, not on every retry.

Send readers to your own game page when they pick a row:

```js
document.querySelector("statpad-scores").addEventListener("statpad-select", (e) => {
  location.href = `/games/${e.detail.league}/${e.detail.game}`;
});
```

## States and messages

Each widget sets `data-state` on its element, so your CSS and scripts can react to it:

| `data-state`         | What the reader sees                                               |
| -------------------- | ------------------------------------------------------------------ |
| `loading`            | A placeholder, until the first data arrives                        |
| `pregame`            | The start time, and a countdown in an expanded scoreboard          |
| `live`               | The game in progress                                               |
| `break`              | Halftime or a delay                                                |
| `final`              | The final score                                                    |
| `off`                | A postponed, suspended or cancelled game                           |
| `reconnecting`       | The last data, with a **Reconnecting** note and a **Retry** button |
| `unavailable`        | A message instead of the game, from the table below                |
| `origin_not_allowed` | **Not available on this site**                                     |

**Reconnecting** appears when checks are failing, such as on a phone that just lost signal, or when Statpad's feed for a live game has fallen behind. The score stays up meanwhile. When checks keep failing for about two minutes, the widget shows **Score unavailable**. It recovers on its own when checks succeed again.

The message a widget shows tells you what to fix:

| Message                        | Code                                       | What to do                                                                                    |
| ------------------------------ | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| **Not available on this site** | `origin_not_allowed`                       | Add the page's origin to the key on the Embeds page.                                          |
| **Embed key revoked**          | `key_revoked`                              | Create a new embed key and update the page.                                                   |
| **Embed key not found**        | `key_unknown`                              | Copy the key again from the Embeds page.                                                      |
| **Not included**               | `no_access`                                | The account has no active plan, or doesn't hold the league. Subscribe, or check the league.   |
| **Game not found**             | `not_found`                                | Check the scoreboard's `league` and `game`.                                                   |
| **League not available**       | `not_found`                                | Check the scores list's `league`. Embeds cover [these leagues](/docs/embeds/origins#leagues). |
| **Widget not set up**          | `invalid_request`                          | Check the key and the attributes, such as a `date` out of range.                              |
| **Score unavailable**          | `unavailable`, `rate_limited` or no answer | Nothing to fix on your side. The widget retries.                                              |

After a refusal, a widget checks again once a minute. So once you add the origin or fix the key, open pages recover within a few minutes without a reload.

To hide a widget that can't show anything, select on its state:

```css
statpad-scoreboard[data-state="unavailable"],
statpad-scoreboard[data-state="origin_not_allowed"] {
  display: none;
}
```

A widget pauses while its page is hidden, such as in a background tab, and checks again as soon as the page is shown.

## Browser support

The widgets run in Safari and iOS 16.4 or later and in current Chromium browsers: Chrome, Edge and Android WebView. Older browsers aren't supported.

## React and Vue

The elements are standard custom elements, so they work in any framework without a wrapper. Load the script once, in your HTML or your root layout, then use the elements in your components.

React and Vue both reserve `key` for themselves and never pass it to the element. Use `data-key` for a widget's own key.

**`React`**

```tsx React
import { useEffect, useRef } from "react";

export function Scores({ onPick }: { onPick: (game: string) => void }) {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    const el = ref.current;
    const listener = (e: Event) => onPick((e as CustomEvent<{ game: string }>).detail.game);
    el?.addEventListener("statpad-select", listener);
    return () => el?.removeEventListener("statpad-select", listener);
  }, [onPick]);

  return <statpad-scores ref={ref} league="nba" layout="strip" data-key="statpad_pk_..." />;
}
```

**`Vue`**

```vue Vue
<template>
  <statpad-scores league="nba" layout="strip" data-key="statpad_pk_..." @statpad-select="pick" />
</template>

<script setup lang="ts">
function pick(e: CustomEvent<{ game: string }>) {
  console.log(e.detail.game);
}
</script>
```

React 19 and Vue set an attribute for every prop the element doesn't define as a property, which is all of them, so pass every input as a string attribute. Widgets your app renders after the page loads are picked up as they appear.

In Vue, tell the compiler the `statpad-` tags are custom elements, so it doesn't try to resolve them as components:

**`vite.config.ts`**

```ts title="vite.config.ts"
import vue from "@vitejs/plugin-vue";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("statpad-") } } })],
});
```

In React with TypeScript, declare the two tags in `JSX.IntrinsicElements` so they type-check.