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, paste in the embed you already have, change what you want and copy it back — the builder reads your current settings, so you are adjusting your widget rather than rebuilding it. It also points out anything worth fixing and any reading your gauges publish that you are not showing.
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.
For a single change to a single widget, editing that one attribute by hand is still quicker. Importing earns its keep when you want to see everything at once, or when a page has several embeds you have not looked at in a while.
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.
Builder only Changes the tool at riverwidget.com, not the widget. Embeds already on a site are untouched and behave exactly as before.
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.6.3 Automatic 4 November 2026
The widget no longer disappears on Shopify’s Dawn theme
Dawn, and themes built on it, hide empty elements with div:empty{display:none}.
The widget draws inside a shadow root, which leaves its outer element looking empty to the
page, so the theme hid the whole card. The script loaded, the data arrived and the console
stayed clear, yet nothing appeared on the page. The widget now holds its own
display against that rule, and existing embeds need no edit.
One side effect: a page stylesheet can no longer hide .riverwidget-host
directly. To hide a widget from your own CSS, for example on small screens, target an
element around it.
2.6.2 Automatic 11 October 2026
Footer text is easier to read
The footer — reading time, provisional notice and station ID — goes from 11px to 12px, and the USGS tag from 10px to 11px. Small text is where a phone reader gives up first, and the reading time is the line that tells someone whether a number is current.
The “River Widget” link under the card is legible on any page
It sits outside the card, on your page, whose background the widget cannot know. It was drawn in the theme’s muted colour at 70% strength, which measured 2.6:1 against a light page — well under the 4.5:1 that WCAG asks of text. It now takes the colour of the text around it, which your site has already made readable on that background. Expect it to look a little stronger than before.
Slate theme passes contrast
Slate’s muted colour, used for labels, units and the footer, measured 4.43:1 on Slate’s own background, just under the 4.5:1 minimum. It is a shade darker.
2.6.1 Automatic 16 September 2026
The footer fits on one line when there is room for one
2.6.0 stopped the reading time breaking in half, but did it by forcing the provisional notice onto its own line — so a wide card showed three lines where one would have done.
The footer is now a wrapping row. It fits on a single line when the card is wide enough, and breaks between its parts when it is not, so a date or a station number never splits down the middle. The two long parts — the provisional sentence and the USGS credit — can still wrap internally on a very narrow card, because keeping those whole is what used to push them past the edge.
2.6.0 Automatic Builder only 15 September 2026
Very old readings are no longer shown as readings
USGS returns the last value a gauge ever produced, however long ago that was. A station
retired in 1997 still answers with a plausible-looking flow figure — and the card
was rendering it as a number under the date Sep 30, with no year, which
reads as a fortnight ago.
Two changes. The year now appears whenever a reading is not from the current year, so an old date looks old. And past about a month, the card stops showing a figure and says when the gauge last reported instead — “No recent readings. This gauge last reported on 5/18/2026, about 4 months ago.”
A gauge down for a week of maintenance is unaffected: it still shows its last number with the Delayed flag, which is useful context. The change only affects readings old enough that a number would mislead — a gauge pulled for the winter, or one retired years ago.
If you embed a seasonal gauge, expect this card over the winter rather than a stale figure. It names the date and explains that gauges are pulled for ice, taken down for maintenance, and sometimes retired, so a visitor knows the widget is working and the river is not being measured.
The footer wraps more sensibly
On a narrow card the reading time could break in half —
Updated 9/13/2026 - on one line with 9:15pm stranded on the
next, which reads as two broken things rather than one date. The timestamp now stays
whole, and the provisional notice starts the line below it.
Import an embed you already have Builder only
New in the builder: Already have an embed? Import it, above step one. Paste the embed from your site and it loads your settings, so you can adjust one thing and copy it back rather than rebuilding from scratch. Nothing on your site changes until you paste the new code.
It reads the paste in your browser and sends it nowhere. Alongside your settings it shows anything worth fixing, options your embed does not use, and what you have changed since importing.
The one worth knowing about: it tells you when a gauge publishes a reading your embed is not showing. Water temperature is the usual case — only about one gauge in six has a thermometer, so it is easy to have one and never find out.
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.