1 Choose a gauge
Try a river name plus a town — “madison ennis”, “deschutes bend” — or paste a USGS site number.
2 Style it
Colours
Each swatch overrides the theme. Clear one to hand it back.
Card
Turn the background and border off to sit the readings straight on your own section — useful above the fold, or inside a card your theme already draws.
Chart
A bare trend line, no axes — reads at a glance in a sidebar.
Axis numbers and day labels stay either way — only the lines go.
Readings
3 Preview
4 Copy the code
Recommended. Inherits your site’s fonts and resizes with its container.
Pick a gauge to generate your embed code.Paste into any HTML block — Elementor HTML widget, WordPress Custom HTML, Squarespace Code Block, Shopify theme, or straight into your page source.
Works where you need it
Any CMS
WordPress and Elementor, Squarespace, Wix, Shopify, Joomla, Drupal, Blogger, Webflow, Ghost, or a hand-written HTML file. If it takes an HTML block, it takes this.
Any browser
Modern browsers get full style isolation via Shadow DOM. Older ones, back to IE11, fall back to a scoped inline render. With JavaScript off entirely, the embed stays a working link to the USGS station page.
Any layout
Sizes to its container, not to the viewport — full-width band, narrow sidebar or phone, without a media query on your end. Up to six gauges per embed, and as many embeds per page as the design wants: the loader is id-guarded, so the script still loads once. See examples.
No dependencies
One script, about 12 KB over the wire, no jQuery, no framework, nothing to install server-side. It never blocks your page: the widget loads after your content.
Straight from USGS
The widget reads api.waterdata.usgs.gov directly from your visitor's browser, so the number on your page is the number USGS is serving — it matches the official station page and every river app, to the minute. We are not in the middle of your data.
No cookies, no tracking
No GA4, no GTM, no beacon, no localStorage, no fingerprint, no visitor
identifier of any kind. Embedding this adds nothing to your consent banner.
Free, including commercially
No sign-up, no email, no API key, no quota. Use it on client sites and charge for the build. The code is MIT — fork it and host your own if you would rather.
What we count, and what we don’t
The widget ships with no analytics whatsoever. We count usage from the server request the widget already makes — the same way a web server counts page views — so nothing is stored on your visitors’ devices.
| Recorded | The embedding domain, the theme, which gauge, and a coarse country from Cloudflare. |
|---|---|
| Never recorded | IP addresses, user agents, session or visitor identifiers, and anything about the page the widget sits on beyond its domain. |
| Stored on the visitor | Nothing. No cookie, no local storage, no cache key tied to a person. |
| Shared publicly | Aggregate totals only — the install count above. Never a list of sites. |
Licensing
The data
U.S. public domain. The readings come from the U.S. Geological Survey’s National Water Information System. As a work of the U.S. Government it carries no copyright: free to use, adapt and redistribute, commercially included, with no permission required. USGS asks only to be credited as the source — the widget does that on every card, and that credit is not removable.
The provisional notice
Real-time readings are provisional until USGS reviews them, and the notice has to travel with them. Every card carries it. Read the full statement →
The code
MIT. The widget, this builder and the edge API are all MIT licensed. Use it, fork it, self-host it, ship it to clients. Machine-readable licence →
Every option
| Attribute | Values | What it does |
|---|---|---|
data-sites | USGS site numbers, comma-separated | Which gauges to show. Up to six per embed. |
data-labels | text, separated by | | Your own names. Blank uses the official USGS station name. |
data-theme | river · slate · forest · sand · night · mono · bare | Colour set. bare inherits everything from your site. |
data-accent | a hex colour | Overrides the theme’s accent for the sparkline and trend pill. |
data-radius | e.g. 12px | Corner radius on the card. |
data-metrics | flow, stage, temp, trend | Which readings appear, comma-separated. |
data-chart | spark · hydrograph · none | Sparkline is the bare trend line. Hydrograph is the USGS-style chart with a real axis and day labels. |
data-chart-days | sparkline 7–60 · hydrograph 1–14 | How far back the chart reaches. Defaults: 14 days sparkline, 7 days hydrograph. |
data-chart-param | flow · stage | Whether the chart plots streamflow or gauge height. |
data-bg | a hex colour, or transparent | Card background. Transparent sits the readings on whatever is behind them. |
data-border | a hex colour, or none | Card border. |
data-text | a hex colour | Body text. |
data-value-color | a hex colour | The big readings. Defaults to data-text. |
data-muted | a hex colour | Labels, units and the footnote. |
data-grid-color | a hex colour | Hydrograph gridlines and axis rules. |
data-gridlines | both · horizontal · vertical · none | Which hydrograph gridlines to draw. Axis numbers and day labels stay either way. |
data-shadow | 0 · 1 | A soft drop shadow under the card. |
data-density | comfortable · compact | Compact tightens padding and shrinks the numerals — for sidebars and grids. |
data-source | usgs · proxy | usgs (default) reads USGS directly. proxy pins to our cached API. |
data-units | us · metric | cfs and feet, or m³/s and metres. |
data-font | inherit · system | Inherit your site’s typeface, or use a system sans. |
data-tz | IANA zone, e.g. America/Denver | Timezone for the “updated” stamp. Defaults to the gauge’s own. |
data-refresh | seconds, minimum 300 | How often an open page re-checks. Default 900. |
USGS publishes on a 15-minute cycle, so refreshing faster than that gets you the same number twice.