Elements
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:
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.
compactis 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.expandedadds 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.autois 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.
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
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, orautoto follow the reader’s system setting.accent: the colour of live dots, highlights and the moment a score changes.surface:cardhas a background, a border and rounded corners.flushhas 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:
Write colours as hex, #RGB or #RRGGBB. The widget works out text contrast from them, and it can’t from any other form:
- An
accentor--statpad-accentthat isn’t hex is ignored, and the default accent applies. - A
--statpad-surfacethat 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.
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:
A scores list’s statpad-update names the window’s first day and every game in it:
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:
States and messages
Each widget sets data-state on its element, so your CSS and scripts can react to it:
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:
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:
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 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:
In React with TypeScript, declare the two tags in JSX.IntrinsicElements so they type-check.