Changelog
What changed, when, and whether you need to do anything about it.
Don’t want to edit code?
You never have to. Open the builder, set your widget up again and paste the new embed — it comes out with every current option already in it, so you get the newer display and layout settings without hand-editing a single attribute.
Worth knowing so you can judge whether it is worth your time: the fixes are already on your site. Rendering, speed and anything marked Automatic below arrived on their own the next time a visitor loaded the page. A fresh embed is not how you get those — it is how you pick up the new options without touching markup.
The builder does not read an embed you already have, so rebuilding means choosing your gauges and colours again. For one option on one widget, editing that one attribute is quicker. For a page you are revisiting anyway, a fresh embed is the easier route.
Automatic Reaches every embed on
cdn.riverwidget.com/v1/widget.js the next time a visitor loads the page.
You do not need to touch your site. Most releases are this.
Needs an edit Adds an option that only takes effect if you add it to your embed. Your existing embeds keep working exactly as they are — nothing breaks, you simply do not get the new thing until you ask for it.
Pinned to a version like
/2.5.1/widget.js, or self-hosting a copy? Then nothing is automatic; see
each release for what to pick up.
2.5.1 Automatic One new option 13 September 2026
A blank chart now explains itself
A card could show a reading and then an empty space where its chart belonged. The cause is a gauge that does not publish the reading being charted — a hydrograph plots streamflow unless told otherwise, and about one live USGS gauge in five reports gauge height but no streamflow. Those cards now say so.
The builder also warns before you publish one, which it could not previously do: it checked the readings you had ticked but never the chart, which is a separate control.
data-chart-param="stage"
Charts gauge height instead of streamflow for that embed.
A good fit if: one of your gauges has no streamflow record.
Harmless otherwise, and only worth adding to the affected embed — the builder tells you which one. Gauges that publish both are unaffected either way.
Builder settings cleared once
Saved builder selections were reset on this release. Some browsers had stored the example river as a real selection that could not be removed and counted against the six-gauge limit. This affects the builder only, never a published embed.
2.5.0 Automatic 13 September 2026
Search in the builder was broken
Typing a river name did nothing and pressing Enter did nothing; only the Search button worked. A variable used to delay the search was never declared, so both handlers failed silently on every keystroke. If you tried the builder and concluded search was broken, it was. Enter now searches, and the arrow keys move through the results.
Choose several gauges at once
Search results are checkboxes with an Add button. The room shown counts down as you tick, against what is left after the gauges you already have.
A card could come up empty
A gauge that reports something, but none of the readings your embed asked for, rendered as a card with a name and nothing in it. It now says what it does publish instead.
The footer no longer clips
On a narrow card — a sidebar, a three-column grid, a phone — the credit line ran past the card edge and was cut off mid-word. It wraps now, and sits at the foot of the card so footers line up across a row.
2.4.0 Automatic 11 September 2026
A card could lose its chart with no explanation
When a page asks USGS for more than one visitor is allowed in an hour, a chart request could fail while the reading succeeded — leaving a card with numbers, no chart and no warning. Those now fall back to our cached copy and say Cached, rather than quietly rendering an incomplete card.
If you are seeing that on a busy page, the troubleshooting guide has the arithmetic: it is almost always a page carrying many separate widgets.
A correction to our own documentation
Several pages said USGS had retired waterservices.usgs.gov. That
was wrong. It still works today, and USGS has said it will be decommissioned in early
2027. What actually broke embedded river graphs was the nwisweb/graph image
service, which is gone.
2.3.0 Two new options 11 September 2026
Card titles take your page’s text size
The title was pinned at 11px and now matches the body text around it, so a widget in a large-type page no longer has a title in fine print. This one applies automatically.
data-title-size="small"
Pins the card title back to 11px.
A good fit if: you preferred the previous look, or your page’s body text is unusually large.
data-columns="2" … "4"
Sets the maximum number of cards per row for an embed holding several gauges.
A good fit if: you are matching a grid your page already uses.
It is a maximum, not a fixed grid — cards drop to fewer per row as the space narrows, measured against the block the widget sits in rather than the browser window. Leave it off and the cards fit themselves to the space, which suits most pages.
A custom label could appear on the wrong card
With several gauges selected, a label typed in the builder was applied to whichever gauge sorted first while the rest used their USGS names. Labels now apply only to a single gauge, and the builder says so.
2.2.0 Automatic Several new options 10 September 2026
Cached readings are now labelled
When a visitor’s browser cannot reach USGS, the widget falls back to our cached copy. That used to look identical to a live reading. Those cards now say Cached.
The credit link names the station
It read “U.S. Geological Survey” on every card. It now shows the station ID, which is what differs between cards on a page showing eight rivers.
data-time-format, data-provisional, data-tz-label, data-station
Shorten or simplify the footer under each reading.
A good fit if: the footer feels heavy in a compact layout.
The reading time and the provisional notice can be shortened but not removed. The first because a river reading with no time on it is the most dangerous thing this can display, and the second because USGS requires it to travel with real-time data. Why those two are fixed.
data-source="proxy"
Reads the numbers through our API instead of from the visitor’s browser.
A good fit if: one page carries many separately-placed gauges — a river, a paragraph of copy, the next river — or your visitors share a network, such as an office, school or hotel.
USGS allows a visitor 1,000 requests an hour, and each widget on a page spends some of that. With proxy set, the visitor’s browser makes no USGS requests at all, so no limit can reach them however many gauges the page shows. No setup, no registration, and it works for any gauge immediately.
The trade is real: readings can be up to 15 minutes old, and your numbers then depend on our service running rather than only on USGS. The embed still degrades to a working link to the station if we are unreachable — but to a link, not to numbers. Both sides in full.
If your gauges sit together in one grid you probably do not need this: several gauges in one widget cost the same as one, which is usually the cheaper fix.
data-badge="0"
Removes the small “River Widget” link and the line it writes to the console.
A good fit if: a client’s brand guidelines rule it out.
We would rather you left it — it is the only way anyone finds this. But it is a request, not a condition. The longer answer.
2.1.0 6 September 2026
First public release: live streamflow, gauge height and water temperature from any of 10,000+ active USGS stream gauges, with a sparkline or a full hydrograph.
Every release, with the widget file attached, is at github.com/River-Widget → Releases. Questions or something broken? Troubleshooting or open an issue.