Show whether your site passes Core Web Vitals right in your README or footer — on real-user data from
Google, refreshed every day.
A badge that tells the truth about speed
Build and coverage badges show that a project is healthy for developers. A Core Web Vitals badge does
the same for the people who use the site: it states, from Google's own field data, whether real
visitors get a fast, responsive and stable page.
The badge reads "passing" when Largest Contentful Paint, Interaction to Next Paint and Cumulative
Layout Shift are all within Google's "good" thresholds for three out of four visits, and "failing"
otherwise. Pages without enough Chrome traffic for field data show the Lighthouse performance score
instead, so the badge never stays empty.
How it works
- The badge image is served from a cache, so it loads instantly in GitHub, docs or a site footer.
- Once a day a background job asks Google PageSpeed Insights for fresh data for your page.
- If a check fails, the badge keeps the last good result instead of going grey.
- Clicking the badge opens this page with the current metrics, so visitors can see the numbers behind it.
Good thresholds
- LCP up to 2.5 s.
- INP up to 200 ms.
- CLS up to 0.1.
Want to see several pages side by side first? Use the
Bulk Core Web Vitals Test.
FAQ
What does "passing" mean?
The badge uses Google's Core Web Vitals assessment on real-user data from the Chrome UX Report: the page passes when Largest Contentful Paint, Interaction to Next Paint and Cumulative Layout Shift are all "good" at the 75th percentile of visits over the last 28 days.
Why does my badge show a performance score instead?
Google only has real-user data for pages with enough Chrome traffic. Without it, the badge falls back to the Lighthouse performance score from a lab run, colored green from 90, yellow from 50.
How often is the badge updated?
Once a day. The badge is served from a cache so it loads instantly on GitHub; when the result is older than a day, a fresh check runs in the background and the next view shows it.
The badge says "checking…". What now?
The first check of a new address takes up to a minute or two. Reload the page; GitHub picks up the result on its next refresh of the image.
Can I track more than one page?
Yes, add a badge per page. For history, alerts on regressions and scheduled scans of many pages, use a free Pulspeed account or the API.