Skip to navigation
Embeds

Elements

Every attribute, theming option, event and state of the two widgets.

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:

<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.

<statpad-scoreboard league="nfl" game="GAME_ID" variant="auto" theme="auto" surface="card"></statpad-scoreboard>
AttributeValuesDefault
leagueA league alias, such as nfl or ncaabRequired
gameThe game’s id, as in the REST APIRequired
variantauto, compact or expandedauto
themeauto, light or darkauto
accentA hex colour, #RGB or #RRGGBB#2F5BEA
surfacecard or flushcard
data-key, keyAn embed keyThe 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.

<statpad-scores league="ncaaf" date="week" layout="list" max="16"></statpad-scores>
AttributeValuesDefault
leagueA league aliasRequired
datetoday, week or a day as YYYY-MM-DDweek for nfl and ncaaf, today for every other league
layoutlist or striplist
maxThe most games to show, 1 to 10012 for a day, 16 for a week
themeauto, light or darkauto
accentA hex colour, #RGB or #RRGGBB#2F5BEA
surfacecard or flushcard
data-key, keyAn embed keyThe 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. The widget itself does nothing else, so you decide what a row opens.

Dates

dateThe games it shows
todayOne 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.
weekTuesday 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-DDThat 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:

PropertyWhat it setsDefault
--statpad-accentThe accent colour, when the accent attribute isn’t set#2F5BEA
--statpad-font-familyThe fontYour page’s font, then the system font
--statpad-radiusThe corner radius of a card14px
--statpad-surfaceThe background colourWhite in light, #111112 in dark, transparent for flush
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 CustomEvents with the payload in detail. None can be cancelled.

EventWhendetail
statpad-readyThe first data arrivesThe same as statpad-update
statpad-updateAnything 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-errorA request fails with a new code{ code, state }
statpad-selectA reader picks a row in <statpad-scores>{ game, league, state }

These examples use the recorded Bills at Vikings game from Sample responses. 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:

{
"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:

{
"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. 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, 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:

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-stateWhat the reader sees
loadingA placeholder, until the first data arrives
pregameThe start time, and a countdown in an expanded scoreboard
liveThe game in progress
breakHalftime or a delay
finalThe final score
offA postponed, suspended or cancelled game
reconnectingThe last data, with a Reconnecting note and a Retry button
unavailableA message instead of the game, from the table below
origin_not_allowedNot 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:

MessageCodeWhat to do
Not available on this siteorigin_not_allowedAdd the page’s origin to the key on the Embeds page.
Embed key revokedkey_revokedCreate a new embed key and update the page.
Embed key not foundkey_unknownCopy the key again from the Embeds page.
Not includedno_accessThe account has no active plan, or doesn’t hold the league. Subscribe, or check the league.
Game not foundnot_foundCheck the scoreboard’s league and game.
League not availablenot_foundCheck the scores list’s league. Embeds cover these leagues.
Widget not set upinvalid_requestCheck the key and the attributes, such as a date out of range.
Score unavailableunavailable, rate_limited or no answerNothing 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:

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.

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_..." />;
}

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
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.