v2.6.1

Nothing to do. This reaches every embed on the rolling /v1/widget.js path automatically.

The footer fits on one line when there is room for one

2.6.0 stopped the reading time breaking in half — Updated 9/13/2026 - on one line with 9:15pm stranded on the next. It did that by forcing the provisional notice onto its own line, which fixed the split date and introduced a worse problem: three lines on a card wide enough for one, at every width.

The footer is now a wrapping row. It fits on a single line when the card allows, and breaks between its parts when it does not, so a date or a station number never splits down the middle.

The provisional sentence and the USGS credit can still wrap inside themselves on a very narrow card. Keeping those whole is what used to push them past the card edge, where they were clipped mid-word. Inside the credit, the station number and its icon stay together.

Self-hosting

Update to widget-2.6.1.js for the footer fix. Nothing in the USGS API changed.

v2.6.0

Nothing to do. This reaches every embed on the rolling /v1/widget.js path automatically.

Fixed: very old readings were shown as current 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 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.

A visitor saw a believable streamflow figure with a recent-looking date, for a river that stopped being gauged twenty-nine years ago. On a widget people use to decide whether to fish or launch a boat, that is the wrong kind of wrong.

Two changes:

• Dates carry the year whenever a reading is not from the current year, so an old date looks old.
• Past sixty days the card stops showing a figure and names the date instead: "No recent readings. This gauge last reported on 5/18/2026, about 4 months ago. Gauges are pulled for the winter, taken down for maintenance, and sometimes retired."

A gauge down for maintenance or a cold snap is unaffected — it still shows its last number with the Delayed flag, which is useful context. Only readings old enough that a number would mislead are demoted.

If you embed a seasonal gauge, expect this card over the winter rather than a stale figure. It tells your visitors the widget is working and the river is not being measured, which is what they need to know.

Sixty days is a judgement, not a measurement: 96% of gauges report within two days and the remaining 4% spread evenly across every duration from a week to a decade, so there is no point at which an outage becomes a season. It changes what about 2.5% of gauges display.

Fixed: the footer could break a timestamp in half

On a narrow card — a sidebar, a three-column grid, a phone — Updated 9/13/2026 - could end up on one line with 9:15pm stranded on the next. The timestamp now stays whole and the provisional notice starts the line below.

New in the builder: import an existing embed

Already have an embed? Import it, above step one. Paste the embed from your site and the builder loads your settings, so you can change one thing and copy it back rather than rebuilding from scratch. Nothing on your site changes until you paste the new code. The paste is read in your browser and sent nowhere.

Alongside your settings it shows anything worth fixing, options your embed does not use, and what you have changed since importing.

The useful one: 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.

Self-hosting

Update to widget-2.6.0.js for the stale-reading fix. Nothing in the USGS API changed.

v2.5.1

Nothing to do. This reaches every embed on the rolling /v1/widget.js path automatically.

Fixed: a chart could be blank with no explanation

A card showed a reading and then an empty space where its chart should be. The cause is a gauge that does not publish the parameter being charted — a hydrograph plots streamflow unless told otherwise, and roughly one live USGS gauge in five reports gauge height but no streamflow.

Found on a live site: Bogachiel River near La Push (12043015) publishes gauge height and water temperature only. That card now reads "No streamflow record for this gauge — it publishes gauge height."

The builder now warns before you publish one

Choosing a chart parameter a selected gauge does not carry produces a warning — "Bogachiel River does not report streamflow, so the chart will be empty. Chart gauge height instead." It previously checked which readings you had ticked but never the chart, which is a separate control.

Optional: data-chart-param

If one of your gauges has this problem, add to that embed only:

data-chart-param="stage"

The chart then plots gauge height instead of streamflow. This is an edit to your embed — existing embeds keep charting streamflow until you change them.

Builder settings reset once

Saved builder selections are cleared on next load. A flag marking the example river as a placeholder was added without changing the storage version, so some browsers had restored that example as a real, undeletable selection that counted against the six-gauge limit. Clearing is the reliable fix; the alternative risked deleting a river someone had actually chosen.

Self-hosting

Update to widget-2.5.1.js to get the chart fix. Nothing in the USGS API changed.

v2.5.0

Fixed: search in the builder did nothing

Typing a river name did nothing, and pressing Enter did nothing. Only the Search button worked. A variable used to debounce the search box was never declared, and because the file runs in strict mode, both handlers threw on their first line — every keystroke, silently. It was the button alone that never touched it.

This had been the state of the primary interaction for months. If you tried the builder and concluded search was broken, it was.

Enter now does what the Search button does. Arrow keys move through the results and Enter or Space adds one.

New: choose several gauges at once

Results are now checkbox rows with an Add button. The count on the button is what you have ticked, and the room shown counts down as you tick — with three gauges already in the embed it offers three, and the checkboxes stop there rather than letting you select more than will fit.

Fixed: 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. About one live USGS gauge in five publishes gauge height but no streamflow, so a flow-only grid meets one sooner or later. That card now reads "This gauge does not report streamflow. It publishes gauge height." and links to the station.

Fixed: the footer clipped on narrow cards

The credit line was held on one line whatever the width, so on a sidebar, a three-column grid or a phone it ran past the card edge and was cut off mid-word. It wraps now. The footer also sits at the foot of the card, so footers line up across a row of cards holding different numbers of readings.

Changed: column counts respond to the space, not the window

data-columns is a maximum rather than a fixed grid. Three across becomes two, then one, as the space narrows — and it measures the block the widget sits in rather than the browser window. A three-across embed inside a 300px sidebar on a wide monitor now behaves the same as it does on a phone.

This matters if you use a theme with its own breakpoints: what those change is how wide the widget's container is, and the widget responds to that. There are no viewport media queries left in the widget at all, so the two sets can no longer disagree.

Also

• The card title can inherit your page's text size (data-title-size), rather than being pinned at 11px.
• A custom label is no longer applied to the wrong card when several gauges are selected.
• INSTALLING.md covers what a grid does with gauges that are not alike.
• The examples page has a six-gauge grid you can resize, with a live readout of the block width and how many cards are across.

Self-hosting

No action needed. Nothing in the USGS API changed.

v2.4.0

Fixed: a card could lose its chart with no explanation

A page with many embeds can exhaust the USGS request allowance for a visitor's IP. When that happened to a chart request, the widget ignored it and rendered the card anyway — numbers, no chart, no warning, and no fallback, because the main reading had arrived. The visible symptom was a chart that came and went between refreshes.

A requested read that fails now sends the whole card to the fallback, where our cached copy usually supplies the missing piece, and the console says what was lost. An empty result still means the gauge publishes nothing, which is not an error.

data-source="proxy" no longer shows the "Cached" notice

Reading through our API because the embed asked to is not a degradation, and it should not wear the same label as one.

The "Cached" notice is shorter

It read Cached data from 9/10/2026, taken from the same timestamp as the Updated line directly above it — so every fallback card printed the date twice and wrapped the footer onto two lines. It now reads Cached.

New: how many requests a page makes

INSTALLING.md now carries the arithmetic, and it is worth knowing before building a large page:

• Each embed costs up to three USGS requests — current reading, 6-hour trend, chart.
• That is per embed, not per gauge. Six gauges in one embed cost exactly what one gauge costs.
• USGS allows 1,000 requests per hour per IP address.

So ten rivers as ten separate embeds is 30 requests per page load; as two embeds of five it is 6. If a layout genuinely needs gauges placed separately, data-source="proxy" makes zero USGS requests from the visitor's browser — the FAQ sets out both sides of that trade.

There is also a new troubleshooting branch for "it changes on refresh", which is the signature of this problem.

Correction to our own documentation

Several pages said USGS had retired waterservices.usgs.gov. That was wrong: it still answers today, and USGS has said it will be decommissioned in early 2027. The service that actually broke embedded river graphs was the nwisweb/graph image endpoint, which is gone. Anything still built on waterservices has a deadline, but it has not passed.

Self-hosting

No action needed. Nothing in the USGS API changed.

v2.3.0

Card title inherits your page's text size. It was pinned at 11px; it now matches the body copy around it. If you preferred the old look, data-title-size="small" puts it back.

New Layout options. Set a fixed number of cards per row (data-columns="2" … "4") instead of letting them fit automatically. A fixed count drops to one per row on phone-width screens.

Fixed: 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 station names — so a card could read "Hoh River" while showing the Calawah. Labels now apply only when a single gauge is selected, and the builder says so. If you have a multi-gauge embed with a data-labels value that does not contain a |, regenerate it.

Self-hosting: no action needed. Nothing in the USGS API changed.

v2.2.0

Adds a dated "Cached data from M/D/YYYY" notice when a visitor's browser cannot reach USGS and the reading is served from our cache instead. Previously that render looked identical to a live one.

A small River Widget badge, an identifying id and data-riverwidget on the host element, and one console line. data-badge="0" removes all three.

Footer controls. The reading time shortens to 9/10/2026 - 8:04am or 9/10/26 - 8a, the provisional notice to one word, and the station ID, its label and the timezone can be turned off. The reading time, the provisional notice and the USGS credit have no off switch — the first two because a river number with no date on it is the most dangerous thing this can render, and USGS requires the provisional disclaimer to travel with real-time data.

The attribution link now names the station rather than reading "U.S. Geological Survey" on every card.

Self-hosting: no action needed. Nothing in the USGS API changed.

v2.1.0

First pinnable release. Two paths are now published:

Path	Behaviour
https://cdn.riverwidget.com/v1/widget.js	Rolling — always the newest build. This is what the builder generates, and what most sites should use.
https://cdn.riverwidget.com/2.1.0/widget.js	Pinned — frozen and cached for a year. Never changes.

Pin if you need change control: an SLA, a locked-down environment, or a client who tests before moving. Otherwise stay on the rolling path — it is the one that gets fixed when USGS changes something.

Self-hosters: no action needed. This release changes nothing about the USGS API. See SELF-HOSTING.md.

In this release

• Hydrograph gridlines are configurable — data-gridlines takes both, horizontal, vertical or none. Axis numbers and day labels stay either way.
• Seven colours can be set independently: data-accent, data-value-color, data-text, data-muted, data-bg, data-border, data-grid-color.
• Console diagnostics. Everything the widget reports is prefixed [River Widget vX], and RiverWidget.diagnose() prints the version, every embed on the page, what each asked for, and recent errors.
• Multiple embeds per page are guarded — the loader is id-based, so pasting the snippet alongside every embed still loads the script once.
• Station names keep their state codes uppercase when a label is not supplied (Clearwater, WA, not Clearwater, Wa).

Fixed

• The file banner reported v1.0.0 while the runtime reported 2.0.0.