Repository: GoogleChrome/web-vitals Branch: main Commit: 8e4e68944724 Files: 91 Total size: 430.7 KB Directory structure: gitextract_ttgfkz8n/ ├── .editorconfig ├── .github/ │ └── workflows/ │ ├── lint.yml │ └── tests.yml ├── .gitignore ├── .husky/ │ ├── .gitignore │ └── pre-commit ├── .nvmrc ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── attribution.d.ts ├── attribution.js ├── docs/ │ ├── upgrading-to-v4.md │ └── upgrading-to-v5.md ├── eslint.config.js ├── package.json ├── rollup.config.js ├── src/ │ ├── attribution/ │ │ ├── index.ts │ │ ├── onCLS.ts │ │ ├── onFCP.ts │ │ ├── onINP.ts │ │ ├── onLCP.ts │ │ └── onTTFB.ts │ ├── index.ts │ ├── lib/ │ │ ├── InteractionManager.ts │ │ ├── LCPEntryManager.ts │ │ ├── LayoutShiftManager.ts │ │ ├── bfcache.ts │ │ ├── bindReporter.ts │ │ ├── doubleRAF.ts │ │ ├── generateUniqueID.ts │ │ ├── getActivationStart.ts │ │ ├── getLoadState.ts │ │ ├── getNavigationEntry.ts │ │ ├── getSelector.ts │ │ ├── getVisibilityWatcher.ts │ │ ├── initMetric.ts │ │ ├── initUnique.ts │ │ ├── observe.ts │ │ ├── polyfills/ │ │ │ ├── getFirstHiddenTimePolyfill.ts │ │ │ └── interactionCountPolyfill.ts │ │ ├── runOnce.ts │ │ ├── whenActivated.ts │ │ └── whenIdleOrHidden.ts │ ├── onCLS.ts │ ├── onFCP.ts │ ├── onINP.ts │ ├── onLCP.ts │ ├── onTTFB.ts │ ├── types/ │ │ ├── base.ts │ │ ├── cls.ts │ │ ├── fcp.ts │ │ ├── inp.ts │ │ ├── lcp.ts │ │ └── ttfb.ts │ └── types.ts ├── test/ │ ├── css/ │ │ └── styles.css │ ├── e2e/ │ │ ├── onCLS-test.js │ │ ├── onFCP-test.js │ │ ├── onINP-test.js │ │ ├── onLCP-test.js │ │ └── onTTFB-test.js │ ├── script/ │ │ ├── async.js │ │ └── defer.js │ ├── server.js │ ├── tsconfig.json │ ├── unit/ │ │ ├── attribution-test.js │ │ ├── bindReporter-test.js │ │ └── index-test.js │ ├── utils/ │ │ ├── assertIsCloseTo.js │ │ ├── beacons.js │ │ ├── browserSupportsEntry.js │ │ ├── domReadyState.js │ │ ├── firstContentfulPaint.js │ │ ├── imagesPainted.js │ │ ├── navigateTo.js │ │ ├── nextFrame.js │ │ ├── stubForwardBack.js │ │ ├── stubVisibilityChange.js │ │ ├── waitUntilIdle.js │ │ └── webVitalsLoaded.js │ └── views/ │ ├── cls.njk │ ├── fcp.njk │ ├── inp.njk │ ├── layout.njk │ ├── lcp.njk │ └── ttfb.njk ├── tsconfig.json └── wdio.conf.js ================================================ FILE CONTENTS ================================================ ================================================ FILE: .editorconfig ================================================ # editorconfig.org # For Visual Studio code use this extension to enforce below rules: # https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig # Other IDEs maye have built in editorconfig support, or their own extensions # # The similar .ecrc file is used by an editorconfig GitHub action to catch those # that don't use this. root = true [*] indent_style = space indent_size = 2 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true ================================================ FILE: .github/workflows/lint.yml ================================================ name: Lint Code Base permissions: contents: read on: pull_request: push: branches: - main workflow_dispatch: jobs: lint: name: Lint Code Base runs-on: ubuntu-latest steps: - name: Checkout Code uses: actions/checkout@v6 - name: NPM install run: npm install - name: Run Prettier run: npm run format:check - name: Run ESlint run: npm run lint ================================================ FILE: .github/workflows/tests.yml ================================================ name: Run tests permissions: contents: read on: pull_request: push: branches: - main workflow_dispatch: jobs: unit-tests: name: Run unit tests # Doesn't require anything special so let's use ubuntu as more available runs-on: ubuntu-latest steps: - name: Checkout Code uses: actions/checkout@v6 - name: NPM install run: npm install - name: Build run: npm run build - name: Run unit tests run: npm run test:unit chrome-tests: name: Run Chrome e2e tests # Runs best on macos for CI as linux requires extra chrome flags runs-on: macos-latest steps: - name: Checkout Code uses: actions/checkout@v6 - name: NPM install run: npm install - name: Build run: npm run build - name: Run server run: npm run test:server & - name: Run e2e tests for chrome run: npm run test:e2e -- --browsers=chrome firefox-tests: name: Run Firefox e2e tests # Runs best on macos for CI as linux requires extra setup runs-on: macos-latest steps: - name: Checkout Code uses: actions/checkout@v6 - name: NPM install run: npm install - name: Build run: npm run build - name: Run server run: npm run test:server & - name: Run e2e tests for firefox run: npm run test:e2e -- --browsers=firefox safari-tests: name: Run Safari e2e tests # Requires macos runs-on: macos-latest steps: - name: Checkout Code uses: actions/checkout@v6 - name: NPM install run: npm install - name: Build run: npm run build - name: Run server run: npm run test:server & - name: Run e2e tests for safari run: npm run test:e2e -- --browsers=safari ================================================ FILE: .gitignore ================================================ .DS_Store .vscode node_modules # Log files *.log # Generated TypeScript files and build data tsconfig.tsbuildinfo # Dist files dist ================================================ FILE: .husky/.gitignore ================================================ _ ================================================ FILE: .husky/pre-commit ================================================ lint-staged grep -r "\.only(" test/e2e \ && echo "ERROR: found .only() use in test" && exit 1 grep -r "browser\.debug(" test/e2e \ && echo "ERROR: found browser.debug() use in test" && exit 1 exit 0 ================================================ FILE: .nvmrc ================================================ lts/Hydrogen ================================================ FILE: CHANGELOG.md ================================================ # Changelog ### v5.1.0 (2025-07-31) - Register `visibility-change` early ([#637](https://github.com/GoogleChrome/web-vitals/pull/637)) - Only finalize LCP on user events (`isTrusted=true`) ([#635](https://github.com/GoogleChrome/web-vitals/pull/635)) - Fallback to default `getSelector` if custom function is null or undefined ([#634](https://github.com/GoogleChrome/web-vitals/pull/634)) ### v5.0.3 (2025-06-11) - Remove visibilitychange event listeners when no longer required ([#627](https://github.com/GoogleChrome/web-vitals/pull/627)) ### v5.0.2 (2025-05-29) - Handle layout shifts with no sources ([#623](https://github.com/GoogleChrome/web-vitals/pull/623)) ### v5.0.1 (2025-05-13) - Fix missing FCP and LCP for prerendered pages ([#621](https://github.com/GoogleChrome/web-vitals/pull/621)) ### v5.0.0 (2025-05-07) [!NOTE] See the [upgrading to v5](/docs/upgrading-to-v5.md) guide for a complete list of all API changes in version 5. - **[BREAKING]** Remove the deprecated `onFID()` function ([#519](https://github.com/GoogleChrome/web-vitals/pull/519)) - **[BREAKING]** Change browser support policy to Baseline Widely available ([#525](https://github.com/GoogleChrome/web-vitals/pull/525)) - **[BREAKING]** Sort the classes that appear in attribution selectors to reduce cardinality ([#518](https://github.com/GoogleChrome/web-vitals/pull/518)) - Extend INP attribution with extra LoAF information: longest script and buckets ([#592](https://github.com/GoogleChrome/web-vitals/pull/592)) - Add support for generating custom targets in the attribution build ([#585](https://github.com/GoogleChrome/web-vitals/pull/585)) - Support multiple calls to `onINP()` with different config options ([#583](https://github.com/GoogleChrome/web-vitals/pull/583)) - Use visibility-state performance entries ([#612](https://github.com/GoogleChrome/web-vitals/pull/612)) - Ensure idle callbacks don't run twice ([#541](https://github.com/GoogleChrome/web-vitals/pull/541)) and ([#548](https://github.com/GoogleChrome/web-vitals/pull/548)) - Cap `nextPaintTime` at `processingStart` ([#540](https://github.com/GoogleChrome/web-vitals/pull/540)) and ([#546](https://github.com/GoogleChrome/web-vitals/pull/546)) - Cap INP breakdowns to INP duration ([#528](https://github.com/GoogleChrome/web-vitals/pull/528)) - Cap LCP load duration to LCP time ([#527](https://github.com/GoogleChrome/web-vitals/pull/527)) ### v4.2.4 (2024-10-22) - Fix memory leak in registering new event listeners on every keydown and click ([#554](https://github.com/GoogleChrome/web-vitals/pull/554)) ### v4.2.3 (2024-08-06) - Fix missing LoAF entries in INP attribution ([#512](https://github.com/GoogleChrome/web-vitals/pull/512)) ### v4.2.2 (2024-07-17) - Fix interaction count after bfcache restore ([#505](https://github.com/GoogleChrome/web-vitals/pull/505)) ### v4.2.1 (2024-06-30) - Fix compatibility issues with TypeScript v5.5 ([#497](https://github.com/GoogleChrome/web-vitals/pull/497)) ### v4.2.0 (2024-06-20) - Refactor INP attribution code to fix errors on Windows 10 ([#495](https://github.com/GoogleChrome/web-vitals/pull/495)) ### v4.1.1 (2024-06-10) - Fix pending LoAF cleanup logic ([#493](https://github.com/GoogleChrome/web-vitals/pull/493)) ### v4.1.0 (2024-06-06) - Move the support check to the top of the onINP() function ([#490](https://github.com/GoogleChrome/web-vitals/pull/490)) - Fix missing LoAF attribution when entries are dispatched before event entries ([#487](https://github.com/GoogleChrome/web-vitals/pull/487)) ### v4.0.1 (2024-05-21) - Add the `ReportCallback` type back but deprecate it ([#483](https://github.com/GoogleChrome/web-vitals/pull/483)) ### v4.0.0 (2024-05-13) [!NOTE] See the [upgrading to v4](/docs/upgrading-to-v4.md) guide for a complete list of all API changes in version 4. - **[BREAKING]** Update types to support more generic usage ([#471](https://github.com/GoogleChrome/web-vitals/pull/471)) - **[BREAKING]** Split `waitingDuration` to make it easier to understand redirect delays ([#458](https://github.com/GoogleChrome/web-vitals/pull/458)) - **[BREAKING]** Rename `TTFBAttribution` fields from `*Time` to `*Duration` ([#453](https://github.com/GoogleChrome/web-vitals/pull/453)) - **[BREAKING]** Rename `resourceLoadTime` to `resourceLoadDuration` in LCP attribution ([#450](https://github.com/GoogleChrome/web-vitals/pull/450)) - **[BREAKING]** Add INP breakdown timings and LoAF attribution ([#442](https://github.com/GoogleChrome/web-vitals/pull/442)) - **[BREAKING]** Deprecate `onFID()` and remove previously deprecated APIs ([#435](https://github.com/GoogleChrome/web-vitals/pull/435)) - Expose the target element in INP attribution ([#479](https://github.com/GoogleChrome/web-vitals/pull/479)) - Save INP target after interactions to reduce null values when removed from the DOM ([#477](https://github.com/GoogleChrome/web-vitals/pull/477)) - Cap TTFB in attribution ([#440](https://github.com/GoogleChrome/web-vitals/pull/440)) - Fix `reportAllChanges` behavior for LCP when library is loaded late ([#468](https://github.com/GoogleChrome/web-vitals/pull/468)) ### v3.5.2 (2024-01-25) - Pick the first non-null `target` for INP attribution ([#421](https://github.com/GoogleChrome/web-vitals/pull/421)) ### v3.5.1 (2023-12-27) - Add extra guard for `PerformanceEventTiming` not existing ([#403](https://github.com/GoogleChrome/web-vitals/pull/403)) ### v3.5.0 (2023-09-28) - Run `onLCP` callback in separate task ([#386](https://github.com/GoogleChrome/web-vitals/pull/386)) - Fix INP durationThreshold bug when set to 0 ([#372](https://github.com/GoogleChrome/web-vitals/pull/372)) - Prevent FID entries being emitted as INP for non-supporting browsers ([#368](https://github.com/GoogleChrome/web-vitals/pull/368)) ### v3.4.0 (2023-07-11) - Make `bindReporter` generic over metric type ([#359](https://github.com/GoogleChrome/web-vitals/pull/359)) - Update INP status in README ([#362](https://github.com/GoogleChrome/web-vitals/pull/362)) - Fix Metric types for better TypeScript support ([#356](https://github.com/GoogleChrome/web-vitals/pull/356)) - Fix selector for SVGs for attribution build ([#354](https://github.com/GoogleChrome/web-vitals/pull/354)) ### v3.3.2 (2023-05-29) - Fix attribution types ([#348](https://github.com/GoogleChrome/web-vitals/pull/348)) - Safe access navigation entry type ([#290](https://github.com/GoogleChrome/web-vitals/pull/290)) ### v3.3.1 (2023-04-04) - Export metric rating thresholds in attribution build as well. ### v3.3.0 (2023-03-09) - Export metric rating thresholds, add explicit `MetricRatingThresholds` type ([#323](https://github.com/GoogleChrome/web-vitals/pull/323)) - Trim classname selector ([#328](https://github.com/GoogleChrome/web-vitals/pull/328)) - Add link to CrUX versus RUM blog post ([#327](https://github.com/GoogleChrome/web-vitals/pull/327)) - Prevent LCP being reported for hidden prerendered pages ([#326](https://github.com/GoogleChrome/web-vitals/pull/326)) - Add Server Timing information to docs ([#324](https://github.com/GoogleChrome/web-vitals/pull/324)) - Fix link in `onINP()` thresholds comment ([#318](https://github.com/GoogleChrome/web-vitals/pull/318)) - Update web.dev link for `onINP()` ([#307](https://github.com/GoogleChrome/web-vitals/pull/307)) - Add a note about when to load the library ([#305](https://github.com/GoogleChrome/web-vitals/pull/305)) ### v3.2.0 - Version number skipped ### v3.1.1 (2023-01-10) - Defer CLS logic until after `onFCP()` callback ([#297](https://github.com/GoogleChrome/web-vitals/pull/297)) ### v3.1.0 (2022-11-15) - Add support for `'restore'` as a `navigationType` ([#284](https://github.com/GoogleChrome/web-vitals/pull/284)) - Report initial CLS value when `reportAllChanges` is true ([#283](https://github.com/GoogleChrome/web-vitals/pull/283)) - Defer all observers until after activation ([#282](https://github.com/GoogleChrome/web-vitals/pull/282)) - Ignore TTFB for loads where responseStart is zero ([#281](https://github.com/GoogleChrome/web-vitals/pull/281)) - Defer execution of observer callbacks ([#278](https://github.com/GoogleChrome/web-vitals/pull/278)) ### v3.0.4 (2022-10-18) - Clamp LCP and FCP to 0 for prerendered pages ([#270](https://github.com/GoogleChrome/web-vitals/pull/270)) ### v3.0.3 (2022-10-04) - Ensure `attribution` object is always present in attribution build ([#265](https://github.com/GoogleChrome/web-vitals/pull/265)) ### v3.0.2 (2022-09-14) - Set an explicit unpkg dist file ([#261](https://github.com/GoogleChrome/web-vitals/pull/261)) ### v3.0.1 (2022-08-31) - Use the cjs extension for all UMD builds ([#257](https://github.com/GoogleChrome/web-vitals/pull/257)) ### v3.0.0 (2022-08-24) - **[BREAKING]** Add a config object param to all metric functions ([#225](https://github.com/GoogleChrome/web-vitals/pull/225)) - **[BREAKING]** Report TTFB after a bfcache restore ([#220](https://github.com/GoogleChrome/web-vitals/pull/220)) - **[BREAKING]** Only include last LCP entry in metric entries ([#218](https://github.com/GoogleChrome/web-vitals/pull/218)) - Update the metric ID prefix for v3 ([#251](https://github.com/GoogleChrome/web-vitals/pull/251)) - Move the Navigation Timing API polyfill to the base+polyfill build ([#248](https://github.com/GoogleChrome/web-vitals/pull/248)) - Add a metric rating property ([#246](https://github.com/GoogleChrome/web-vitals/pull/246)) - Add deprecation notices for base+polyfill builds ([#242](https://github.com/GoogleChrome/web-vitals/pull/242)) - Add a new attribution build for debugging issues in the field ([#237](https://github.com/GoogleChrome/web-vitals/pull/237), [#244](https://github.com/GoogleChrome/web-vitals/pull/244)) - Add support for prerendered pages ([#233](https://github.com/GoogleChrome/web-vitals/pull/233)) - Rename the `ReportHandler` type to `ReportCallback`, with alias for back-compat ([#225](https://github.com/GoogleChrome/web-vitals/pull/225), [#227](https://github.com/GoogleChrome/web-vitals/pull/227)) - Add support for the new INP metric ([#221](https://github.com/GoogleChrome/web-vitals/pull/221), [#232](https://github.com/GoogleChrome/web-vitals/pull/232)) - Rename `getXXX()` functions to `onXXX()` ([#222](https://github.com/GoogleChrome/web-vitals/pull/222)) - Add a `navigationType` property to the Metric object ([#219](https://github.com/GoogleChrome/web-vitals/pull/219)) ### v2.1.4 (2022-01-20) - Prevent TTFB from reporting after bfcache restore ([#201](https://github.com/GoogleChrome/web-vitals/pull/201)) ### v2.1.3 (2022-01-06) - Only call report if LCP occurs before first hidden ([#197](https://github.com/GoogleChrome/web-vitals/pull/197)) ### v2.1.2 (2021-10-11) - Ensure reported TTFB values are less than the current page time ([#187](https://github.com/GoogleChrome/web-vitals/pull/187)) ### v2.1.1 (2021-10-06) - Add feature detects to support Opera mini in extreme data saver mode ([#186](https://github.com/GoogleChrome/web-vitals/pull/186)) ### v2.1.0 (2021-07-01) - Add batch reporting support and guidance ([#166](https://github.com/GoogleChrome/web-vitals/pull/166)) ### v2.0.1 (2021-06-02) - Detect getEntriesByName support before calling ([#158](https://github.com/GoogleChrome/web-vitals/pull/158)) ### v2.0.0 (2021-06-01) - **[BREAKING]** Update CLS to max session window 5s cap 1s gap ([#148](https://github.com/GoogleChrome/web-vitals/pull/148)) - Ensure CLS is only reported if page was visible ([#149](https://github.com/GoogleChrome/web-vitals/pull/149)) - Only report CLS when FCP is reported ([#154](https://github.com/GoogleChrome/web-vitals/pull/154)) - Update the unique ID version prefix ([#157](https://github.com/GoogleChrome/web-vitals/pull/157)) ### v1.1.2 (2021-05-05) - Ignore negative TTFB values in Firefox ([#147](https://github.com/GoogleChrome/web-vitals/pull/147)) - Add workaround for Safari FCP bug ([#145](https://github.com/GoogleChrome/web-vitals/pull/145)) - Add more extensive FID feature detect ([#143](https://github.com/GoogleChrome/web-vitals/pull/143)) ### v1.1.1 (2021-03-13) - Remove use of legacy API to detect Firefox ([#128](https://github.com/GoogleChrome/web-vitals/pull/128)) ### v1.1.0 (2021-01-13) - Fix incorrect UMD config for base+polyfill script ([#117](https://github.com/GoogleChrome/web-vitals/pull/117)) - Fix missing getter in polyfill ([#114](https://github.com/GoogleChrome/web-vitals/pull/114)) - Add support for Set in place of WeakSet for IE11 compat ([#110](https://github.com/GoogleChrome/web-vitals/pull/110)) ### v1.0.1 (2020-11-16) - Fix missing `typings` declaration ([#90](https://github.com/GoogleChrome/web-vitals/pull/90)) ### v1.0.0 (2020-11-16) - **[BREAKING]** Add support for reporting metrics on back/forward cache restore ([#87](https://github.com/GoogleChrome/web-vitals/pull/87)) - **[BREAKING]** Remove the `isFinal` flag from the Metric interface ([#86](https://github.com/GoogleChrome/web-vitals/pull/86)) - Remove the scroll listener to stop LCP observing ([#85](https://github.com/GoogleChrome/web-vitals/pull/85)) ### v0.2.4 (2020-07-23) - Remove the unload listener ([#68](https://github.com/GoogleChrome/web-vitals/pull/68)) ### v0.2.3 (2020-06-26) - Ensure reports only occur if a PO was created ([#58](https://github.com/GoogleChrome/web-vitals/pull/58)) ### v0.2.2 (2020-05-12) - Remove package `type` field ([#35](https://github.com/GoogleChrome/web-vitals/pull/35)) ### v0.2.1 (2020-05-06) - Ensure all modules are pure modules ([#23](https://github.com/GoogleChrome/web-vitals/pull/23)) - Ensure proper TypeScript exports and config ([#22](https://github.com/GoogleChrome/web-vitals/pull/22)) ### v0.2.0 (2020-05-03) - Initial public release ### v0.1.0 (2020-04-24) - Initial pre-release ================================================ FILE: CODE_OF_CONDUCT.md ================================================ # Google Open Source Community Guidelines At Google, we recognize and celebrate the creativity and collaboration of open source contributors and the diversity of skills, experiences, cultures, and opinions they bring to the projects and communities they participate in. Every one of Google's open source projects and communities are inclusive environments, based on treating all individuals respectfully, regardless of gender identity and expression, sexual orientation, disabilities, neurodiversity, physical appearance, body size, ethnicity, nationality, race, age, religion, or similar personal characteristic. We value diverse opinions, but we value respectful behavior more. Respectful behavior includes: - Being considerate, kind, constructive, and helpful. - Not engaging in demeaning, discriminatory, harassing, hateful, sexualized, or physically threatening behavior, speech, and imagery. - Not engaging in unwanted physical contact. Some Google open source projects [may adopt][] an explicit project code of conduct, which may have additional detailed expectations for participants. Most of those projects will use our [modified Contributor Covenant][]. [may adopt]: https://opensource.google/docs/releasing/preparing/#conduct [modified contributor covenant]: https://opensource.google/docs/releasing/template/CODE_OF_CONDUCT/ ## Resolve peacefully We do not believe that all conflict is necessarily bad; healthy debate and disagreement often yields positive results. However, it is never okay to be disrespectful. If you see someone behaving disrespectfully, you are encouraged to address the behavior directly with those involved. Many issues can be resolved quickly and easily, and this gives people more control over the outcome of their dispute. If you are unable to resolve the matter for any reason, or if the behavior is threatening or harassing, report it. We are dedicated to providing an environment where participants feel welcome and safe. ## Reporting problems Some Google open source projects may adopt a project-specific code of conduct. In those cases, a Google employee will be identified as the Project Steward, who will receive and handle reports of code of conduct violations. In the event that a project hasn’t identified a Project Steward, you can report problems by emailing opensource@google.com. We will investigate every complaint, but you may not receive a direct response. We will use our discretion in determining when and how to follow up on reported incidents, which may range from not taking action to permanent expulsion from the project and project-sponsored spaces. We will notify the accused of the report and provide them an opportunity to discuss it before any action is taken. The identity of the reporter will be omitted from the details of the report supplied to the accused. In potentially harmful situations, such as ongoing harassment or threats to anyone's safety, we may take action without notice. _This document was adapted from the [IndieWeb Code of Conduct][] and can also be found at ._ [indieweb code of conduct]: https://indieweb.org/code-of-conduct ================================================ FILE: CONTRIBUTING.md ================================================ # How to Contribute We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow. ## Contributor License Agreement Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to to see your current agreements on file or to sign a new one. You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again. ## Code reviews All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. ## Testing To test the full suite run `npm run test`. To test a subset of browsers or metrics, run the following in separate terminals: - `npm run watch` - `npm run test:server` - `npm run test:e2e -- --browsers=chrome --metrics=TTFB` The last command can be replaced as you see fit and include comma, separated values. For example: - `npm run test:e2e -- --browsers=chrome,firefox --metrics=TTFB,LCP` To run an individual test, change `it('test name')` to `it.only('test name')`. You can also add `await browser.debug()` lines to the individual test files to pause execution, and press `CTRL+C` in the command line to continue the tests. See the https://webdriver.io/ for more information. ## Community Guidelines This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/). ================================================ FILE: LICENSE ================================================ Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright 2020 Google LLC Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================ FILE: README.md ================================================ # `web-vitals` - [Overview](#overview) - [Install and load the library](#installation) - [From npm](#import-web-vitals-from-npm) - [From a CDN](#load-web-vitals-from-a-cdn) - [Usage](#usage) - [Basic usage](#basic-usage) - [Report the value on every change](#report-the-value-on-every-change) - [Report only the delta of changes](#report-only-the-delta-of-changes) - [Send the results to an analytics endpoint](#send-the-results-to-an-analytics-endpoint) - [Send the results to Google Analytics](#send-the-results-to-google-analytics) - [Send the results to Google Tag Manager](#send-the-results-to-google-tag-manager) - [Send attribution data](#send-attribution-data) - [Batch multiple reports together](#batch-multiple-reports-together) - [Build options](#build-options) - [Which build is right for you?](#which-build-is-right-for-you) - [API](#api) - [Types](#types) - [Functions](#functions) - [Rating Thresholds](#rating-thresholds) - [Attribution](#attribution) - [Browser Support](#browser-support) - [Limitations](#limitations) - [Development](#development) - [Integrations](#integrations) - [License](#license) ## Overview The `web-vitals` library is a tiny (~2K, brotli'd), modular library for measuring all the [Web Vitals](https://web.dev/articles/vitals) metrics on real users, in a way that accurately matches how they're measured by Chrome and reported to other Google tools (e.g. [Chrome User Experience Report](https://developers.google.com/web/tools/chrome-user-experience-report), [Page Speed Insights](https://developers.google.com/speed/pagespeed/insights/), [Search Console's Speed Report](https://webmasters.googleblog.com/2019/11/search-console-speed-report.html)). The library supports all of the [Core Web Vitals](https://web.dev/articles/vitals#core_web_vitals) as well as a number of other metrics that are useful in diagnosing [real-user](https://web.dev/articles/user-centric-performance-metrics) performance issues. ### Core Web Vitals - [Cumulative Layout Shift (CLS)](https://web.dev/articles/cls) - [Interaction to Next Paint (INP)](https://web.dev/articles/inp) - [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp) ### Other metrics - [First Contentful Paint (FCP)](https://web.dev/articles/fcp) - [Time to First Byte (TTFB)](https://web.dev/articles/ttfb) ## Install and load the library The `web-vitals` library uses the `buffered` flag for [PerformanceObserver](https://developer.mozilla.org/docs/Web/API/PerformanceObserver/observe), allowing it to access performance entries that occurred before the library was loaded. This means you do not need to load this library early in order to get accurate performance data. In general, this library should be deferred until after other user-impacting code has loaded. ### From npm You can install this library from npm by running: ```sh npm install web-vitals ``` > [!NOTE] > If you're not using npm, you can still load `web-vitals` via ` ``` Note: When the web-vitals code is isolated from the application code in this way, there is less need to depend on dynamic imports so this code uses a regular `import` line. **Load the "standard" build** _(using a classic script)_ ```html ``` **Load the "attribution" build** _(using a module script)_ ```html ``` **Load the "attribution" build** _(using a classic script)_ ```html ``` ## Usage ### Basic usage Each of the Web Vitals metrics is exposed as a single function that takes a `callback` function that will be called any time the metric value is available and ready to be reported. The following example measures each of the Core Web Vitals metrics and logs the result to the console once its value is ready to report. _(The examples below import the "standard" build, but they will work with the "attribution" build as well.)_ ```js import {onCLS, onINP, onLCP} from 'web-vitals'; onCLS(console.log); onINP(console.log); onLCP(console.log); ``` Note that some of these metrics will not report until the user has interacted with the page, switched tabs, or the page starts to unload. If you don't see the values logged to the console immediately, try reloading the page (with [preserve log](https://developer.chrome.com/docs/devtools/console/reference/#persist) enabled) or switching tabs and then switching back. Also, in some cases a metric callback may never be called: - INP is not reported if the user never interacts with the page. - CLS, FCP, and LCP are not reported if the page was loaded in the background. In other cases, a metric callback may be called more than once: - CLS and INP should be reported any time the [page's `visibilityState` changes to hidden](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden). - All metrics are reported again (with the above exceptions) after a page is restored from the [back/forward cache](https://web.dev/articles/bfcache). > [!WARNING] > Do not call any of the Web Vitals functions (e.g. `onCLS()`, `onINP()`, `onLCP()`) more than once per page load. Each of these functions creates a `PerformanceObserver` instance and registers event listeners for the lifetime of the page. While the overhead of calling these functions once is negligible, calling them repeatedly on the same page may eventually result in a memory leak. ### Report the value on every change In most cases, you only want the `callback` function to be called when the metric is ready to be reported. However, it is possible to report every change (e.g. each larger layout shift as it happens) by setting `reportAllChanges` to `true` in the optional, [configuration object](#reportopts) (second parameter). > [!IMPORTANT] > `reportAllChanges` only reports when the **metric changes**, not for each **input to the metric**. For example, a new layout shift that does not increase the CLS metric will not be reported even with `reportAllChanges` set to `true` because the CLS metric has not changed. Similarly, for INP, each interaction is not reported even with `reportAllChanges` set to `true`—just when an interaction causes an increase to INP. This can be useful when debugging, but in general using `reportAllChanges` is not needed (or recommended) for measuring these metrics in production. ```js import {onCLS} from 'web-vitals'; // Logs CLS as the value changes. onCLS(console.log, {reportAllChanges: true}); ``` ### Report only the delta of changes Some analytics providers allow you to update the value of a metric, even after you've already sent it to their servers (overwriting the previously-sent value with the same `id`). Other analytics providers, however, do not allow this, so instead of reporting the new value, you need to report only the delta (the difference between the current value and the last-reported value). You can then compute the total value by summing all metric deltas sent with the same ID. The following example shows how to use the `id` and `delta` properties: ```js import {onCLS, onINP, onLCP} from 'web-vitals'; function logDelta({name, id, delta}) { console.log(`${name} matching ID ${id} changed by ${delta}`); } onCLS(logDelta); onINP(logDelta); onLCP(logDelta); ``` > [!NOTE] > The first time the `callback` function is called, its `value` and `delta` properties will be the same. In addition to using the `id` field to group multiple deltas for the same metric, it can also be used to differentiate different metrics reported on the same page. For example, after a back/forward cache restore, a new metric object is created with a new `id` (since back/forward cache restores are considered separate page visits). ### Send the results to an analytics endpoint The following example measures each of the Core Web Vitals metrics and reports them to a hypothetical `/analytics` endpoint, as soon as each is ready to be sent. The `sendToAnalytics()` function uses the [`navigator.sendBeacon()`](https://developer.mozilla.org/docs/Web/API/Navigator/sendBeacon) method, which is widely available across browsers, and supports sending data as the page is being unloaded. ```js import {onCLS, onINP, onLCP} from 'web-vitals'; function sendToAnalytics(metric) { const body = JSON.stringify({ name: metric.name, value: metric.value, id: metric.id, // Include additional data as needed... }); // Use `navigator.sendBeacon()` to send the data, which supports // sending while the page is unloading. navigator.sendBeacon('/analytics', body); } onCLS(sendToAnalytics); onINP(sendToAnalytics); onLCP(sendToAnalytics); ``` ### Send the results to Google Analytics Google Analytics does not support reporting metric distributions in any of its built-in reports; however, if you set a unique event parameter value (in this case, the metric_id, as shown in the example below) on every metric instance that you send to Google Analytics, you can create a report yourself by first getting the data via the [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1) or via [BigQuery export](https://support.google.com/analytics/answer/9358801) and then visualizing it any charting library you choose. [Google Analytics 4](https://support.google.com/analytics/answer/10089681) introduces a new Event model allowing custom parameters instead of a fixed category, action, and label. It also supports non-integer values, making it easier to measure Web Vitals metrics compared to previous versions. ```js import {onCLS, onINP, onLCP} from 'web-vitals'; function sendToGoogleAnalytics({name, delta, value, id}) { // Assumes the global `gtag()` function exists, see: // https://developers.google.com/analytics/devguides/collection/ga4 gtag('event', name, { // Built-in params: value: delta, // Use `delta` so the value can be summed. // Custom params: metric_id: id, // Needed to aggregate events. metric_value: value, // Optional. metric_delta: delta, // Optional. // OPTIONAL: any additional params or debug info here. // See: https://web.dev/articles/debug-performance-in-the-field // metric_rating: 'good' | 'needs-improvement' | 'poor', // debug_info: '...', // ... }); } onCLS(sendToGoogleAnalytics); onINP(sendToGoogleAnalytics); onLCP(sendToGoogleAnalytics); ``` For details on how to query this data in [BigQuery](https://cloud.google.com/bigquery), or visualise it in [Looker Studio](https://lookerstudio.google.com/), see [Measure and debug performance with Google Analytics 4 and BigQuery](https://web.dev/articles/vitals-ga4). ### Send the results to Google Tag Manager While `web-vitals` can be called directly from Google Tag Manager, using a pre-defined custom template makes this considerably easier. Some recommended templates include: - [Core Web Vitals](https://tagmanager.google.com/gallery/#/owners/gtm-templates-simo-ahava/templates/core-web-vitals) by [Simo Ahava](https://www.simoahava.com/). See [Track Core Web Vitals in GA4 with Google Tag Manager](https://www.simoahava.com/analytics/track-core-web-vitals-in-ga4-with-google-tag-manager/) for usage and installation instructions. - [Web Vitals Template for Google Tag Manager](https://github.com/google-marketing-solutions/web-vitals-gtm-template) by The Google Marketing Solutions team. See the [README](https://github.com/google-marketing-solutions/web-vitals-gtm-template?tab=readme-ov-file#web-vitals-template-for-google-tag-manager) for usage and installation instructions. ### Send attribution data When using the [attribution build](#attribution-build), you can send additional data to help you debug _why_ the metric values are the way they are. This example sends an additional `debug_target` param to Google Analytics, corresponding to the element most associated with each metric. ```js import {onCLS, onINP, onLCP} from 'web-vitals/attribution'; function sendToGoogleAnalytics({name, delta, value, id, attribution}) { const eventParams = { // Built-in params: value: delta, // Use `delta` so the value can be summed. // Custom params: metric_id: id, // Needed to aggregate events. metric_value: value, // Optional. metric_delta: delta, // Optional. }; switch (name) { case 'CLS': eventParams.debug_target = attribution.largestShiftTarget; break; case 'INP': eventParams.debug_target = attribution.interactionTarget; break; case 'LCP': eventParams.debug_target = attribution.target; break; } // Assumes the global `gtag()` function exists, see: // https://developers.google.com/analytics/devguides/collection/ga4 gtag('event', name, eventParams); } onCLS(sendToGoogleAnalytics); onINP(sendToGoogleAnalytics); onLCP(sendToGoogleAnalytics); ``` > [!NOTE] > This example relies on custom [event parameters](https://support.google.com/analytics/answer/11396839) in Google Analytics 4. See [Debug performance in the field](https://web.dev/articles/debug-performance-in-the-field) for more information and examples. ### Batch multiple reports together Rather than reporting each individual Web Vitals metric separately, you can minimize your network usage by batching multiple metric reports together in a single network request. However, since not all Web Vitals metrics become available at the same time, and since not all metrics are reported on every page, you cannot simply defer reporting until all metrics are available. Instead, you should keep a queue of all metrics that were reported and flush the queue whenever the page is backgrounded or unloaded: ```js import {onCLS, onINP, onLCP} from 'web-vitals'; const queue = new Set(); function addToQueue(metric) { queue.add(metric); } function flushQueue() { if (queue.size > 0) { // Replace with whatever serialization method you prefer. // Note: JSON.stringify will likely include more data than you need. const body = JSON.stringify([...queue]); // Use `navigator.sendBeacon()` to send the data, which supports // sending while the page is unloading. navigator.sendBeacon('/analytics', body); queue.clear(); } } onCLS(addToQueue); onINP(addToQueue); onLCP(addToQueue); // Report all available metrics whenever the page is backgrounded or unloaded. addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') { flushQueue(); } }); ``` > [!NOTE] > See [the Page Lifecycle guide](https://developers.google.com/web/updates/2018/07/page-lifecycle-api#legacy-lifecycle-apis-to-avoid) for an explanation of why `visibilitychange` is recommended over events like `beforeunload` and `unload`. ## Build options The `web-vitals` package includes both "standard" and "attribution" builds, as well as different formats of each to allow developers to choose the format that best meets their needs or integrates with their architecture. The following table lists all the builds distributed with the `web-vitals` package on npm.
Filename (all within dist/*) Export Description
web-vitals.js pkg.module

An ES module bundle of all metric functions, without any attribution features.

This is the "standard" build and is the simplest way to consume this library out of the box.
web-vitals.umd.cjs pkg.main A UMD version of the web-vitals.js bundle (exposed on the self.webVitals.* namespace).
web-vitals.iife.js -- An IIFE version of the web-vitals.js bundle (exposed on the self.webVitals.* namespace).
web-vitals.attribution.js -- An ES module version of all metric functions that includes attribution features.
web-vitals.attribution.umd.cjs -- A UMD version of the web-vitals.attribution.js build (exposed on the self.webVitals.* namespace).
web-vitals.attribution.iife.js -- An IIFE version of the web-vitals.attribution.js build (exposed on the self.webVitals.* namespace).
### Which build is right for you? Most developers will generally want to use "standard" build (via either the ES module or UMD version, depending on your bundler/build system), as it's the easiest to use out of the box and integrate into existing tools. However, if you'd like to collect additional debug information to help you diagnose performance bottlenecks based on real-user issues, use the ["attribution" build](#attribution-build). For guidance on how to collect and use real-user data to debug performance issues, see [Debug performance in the field](https://web.dev/debug-performance-in-the-field/). ## API ### Types: #### `Metric` All metrics types inherit from the following base interface: ```ts interface Metric { /** * The name of the metric (in acronym form). */ name: 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB'; /** * The current value of the metric. */ value: number; /** * The rating as to whether the metric value is within the "good", * "needs improvement", or "poor" thresholds of the metric. */ rating: 'good' | 'needs-improvement' | 'poor'; /** * The delta between the current value and the last-reported value. * On the first report, `delta` and `value` will always be the same. */ delta: number; /** * A unique ID representing this particular metric instance. This ID can * be used by an analytics tool to dedupe multiple values sent for the same * metric instance, or to group multiple deltas together and calculate a * total. It can also be used to differentiate multiple different metric * instances sent from the same page, which can happen if the page is * restored from the back/forward cache (in that case new metrics object * get created). */ id: string; /** * Any performance entries relevant to the metric value calculation. * The array may also be empty if the metric value was not based on any * entries (e.g. a CLS value of 0 given no layout shifts). */ entries: PerformanceEntry[]; /** * The type of navigation. * * This will be the value returned by the Navigation Timing API (or * `undefined` if the browser doesn't support that API), with the following * exceptions: * - 'back-forward-cache': for pages that are restored from the bfcache. * - 'back_forward' is renamed to 'back-forward' for consistency. * - 'prerender': for pages that were prerendered. * - 'restore': for pages that were discarded by the browser and then * restored by the user. */ navigationType: | 'navigate' | 'reload' | 'back-forward' | 'back-forward-cache' | 'prerender' | 'restore'; } ``` Metric-specific subclasses: ##### `CLSMetric` ```ts interface CLSMetric extends Metric { name: 'CLS'; entries: LayoutShift[]; } ``` ##### `FCPMetric` ```ts interface FCPMetric extends Metric { name: 'FCP'; entries: PerformancePaintTiming[]; } ``` ##### `INPMetric` ```ts interface INPMetric extends Metric { name: 'INP'; entries: PerformanceEventTiming[]; } ``` ##### `LCPMetric` ```ts interface LCPMetric extends Metric { name: 'LCP'; entries: LargestContentfulPaint[]; } ``` ##### `TTFBMetric` ```ts interface TTFBMetric extends Metric { name: 'TTFB'; entries: PerformanceNavigationTiming[]; } ``` #### `MetricRatingThresholds` The thresholds of metric's "good", "needs improvement", and "poor" ratings. - Metric values up to and including [0] are rated "good" - Metric values up to and including [1] are rated "needs improvement" - Metric values above [1] are "poor" | Metric value | Rating | | --------------- | ------------------- | | ≦ [0] | "good" | | > [0] and ≦ [1] | "needs improvement" | | > [1] | "poor" | ```ts type MetricRatingThresholds = [number, number]; ``` _See also [Rating Thresholds](#rating-thresholds)._ #### `ReportOpts` ```ts interface ReportOpts { reportAllChanges?: boolean; } ``` Metric-specific subclasses: ##### `INPReportOpts` ```ts interface INPReportOpts extends ReportOpts { durationThreshold?: number; } ``` #### `AttributionReportOpts` A subclass of `ReportOpts` used for each metric function exported in the [attribution build](#attribution). ```ts interface AttributionReportOpts extends ReportOpts { generateTarget?: (el: Node | null) => string | null | undefined; } ``` Metric-specific subclasses: ##### `INPAttributionReportOpts` ```ts interface INPAttributionReportOpts extends AttributionReportOpts { durationThreshold?: number; } ``` #### `LoadState` The `LoadState` type is used in several of the metric [attribution objects](#attribution). ```ts /** * The loading state of the document. Note: this value is similar to * `document.readyState` but it subdivides the "interactive" state into the * time before and after the DOMContentLoaded event fires. * * State descriptions: * - `loading`: the initial document response has not yet been fully downloaded * and parsed. This is equivalent to the corresponding `readyState` value. * - `dom-interactive`: the document has been fully loaded and parsed, but * scripts may not have yet finished loading and executing. * - `dom-content-loaded`: the document is fully loaded and parsed, and all * scripts (except `async` scripts) have loaded and finished executing. * - `complete`: the document and all of its sub-resources have finished * loading. This is equivalent to the corresponding `readyState` value. */ type LoadState = | 'loading' | 'dom-interactive' | 'dom-content-loaded' | 'complete'; ``` ### Functions: #### `onCLS()` ```ts function onCLS(callback: (metric: CLSMetric) => void, opts?: ReportOpts): void; ``` Calculates the [CLS](https://web.dev/articles/cls) value for the current page and calls the `callback` function once the value is ready to be reported, along with all `layout-shift` performance entries that were used in the metric value calculation. The reported value is a [double](https://heycam.github.io/webidl/#idl-double) (corresponding to a [layout shift score](https://web.dev/articles/cls#layout_shift_score)). > [!IMPORTANT] > CLS should be continually monitored for changes throughout the entire lifespan of a page—including if the user returns to the page after it's been hidden/backgrounded. However, since browsers often [will not fire additional callbacks once the user has backgrounded a page](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden), `callback` is always called when the page's visibility state changes to hidden. As a result, the `callback` function might be called multiple times during the same page load (see [Reporting only the delta of changes](#report-only-the-delta-of-changes) for how to manage this). If the `reportAllChanges` [configuration option](#reportopts) is set to `true`, the `callback` function will be called as soon as the value is initially determined as well as any time the value changes throughout the page lifespan (though [not necessarily for every layout shift](#report-the-value-on-every-change)). Note that regardless of whether `reportAllChanges` is used, the final reported value will be the same. #### `onFCP()` ```ts function onFCP(callback: (metric: FCPMetric) => void, opts?: ReportOpts): void; ``` Calculates the [FCP](https://web.dev/articles/fcp) value for the current page and calls the `callback` function once the value is ready, along with the relevant `paint` performance entry used to determine the value. The reported value is a [`DOMHighResTimeStamp`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp). #### `onINP()` ```ts function onINP( callback: (metric: INPMetric) => void, opts?: INPReportOpts, ): void; ``` Calculates the [INP](https://web.dev/articles/inp) value for the current page and calls the `callback` function once the value is ready, along with the `event` performance entries reported for that interaction. The reported value is a [`DOMHighResTimeStamp`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp). > [!IMPORTANT] > INP should be continually monitored for changes throughout the entire lifespan of a page—including if the user returns to the page after it's been hidden/backgrounded. However, since browsers often [will not fire additional callbacks once the user has backgrounded a page](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden), `callback` is always called when the page's visibility state changes to hidden. As a result, the `callback` function might be called multiple times during the same page load (see [Reporting only the delta of changes](#report-only-the-delta-of-changes) for how to manage this). A custom `durationThreshold` [configuration option](#reportopts) can optionally be passed to control the minimum duration filter for `event-timing`. Events which are faster than this threshold are not reported. Note that the `first-input` entry is always observed, regardless of duration, to ensure you always have some INP score. The default threshold, after the library is initialized, is `40` milliseconds (the `event-timing` default of `104` milliseconds applies to all events emitted before the library is initialised). This default threshold of `40` is chosen to strike a balance between usefulness and performance. Running this callback for any interaction that spans just one or two frames is likely not worth the insight that could be gained. If the `reportAllChanges` [configuration option](#reportopts) is set to `true`, the `callback` function will be called as soon as the value is initially determined as well as any time the value changes throughout the page lifespan (though [not necessarily for every interaction](#report-the-value-on-every-change)). Note that regardless of whether `reportAllChanges` is used, the final reported value will be the same. #### `onLCP()` ```ts function onLCP(callback: (metric: LCPMetric) => void, opts?: ReportOpts): void; ``` Calculates the [LCP](https://web.dev/articles/lcp) value for the current page and calls the `callback` function once the value is ready (along with the relevant `largest-contentful-paint` performance entry used to determine the value). The reported value is a [`DOMHighResTimeStamp`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp). If the `reportAllChanges` [configuration option](#reportopts) is set to `true`, the `callback` function will be called any time a new `largest-contentful-paint` performance entry is dispatched, or once the final value of the metric has been determined. Note that regardless of whether `reportAllChanges` is used, the final reported value will be the same. #### `onTTFB()` ```ts function onTTFB( callback: (metric: TTFBMetric) => void, opts?: ReportOpts, ): void; ``` Calculates the [TTFB](https://web.dev/articles/ttfb) value for the current page and calls the `callback` function once the page has loaded, along with the relevant `navigation` performance entry used to determine the value. The reported value is a [`DOMHighResTimeStamp`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp). Note, this function waits until after the page is loaded to call `callback` in order to ensure all properties of the `navigation` entry are populated. This is useful if you want to report on other metrics exposed by the [Navigation Timing API](https://w3c.github.io/navigation-timing/). For example, the TTFB metric starts from the page's [time origin](https://www.w3.org/TR/hr-time-2/#sec-time-origin), which means it includes time spent on DNS lookup, connection negotiation, network latency, and server processing time. ```js import {onTTFB} from 'web-vitals'; onTTFB((metric) => { // Calculate the request time by subtracting from TTFB // everything that happened prior to the request starting. const requestTime = metric.value - metric.entries[0].requestStart; console.log('Request time:', requestTime); }); ``` > [!NOTE] > Browsers that do not support `navigation` entries will fall back to using `performance.timing` (with the timestamps converted from epoch time to [`DOMHighResTimeStamp`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp)). This ensures code referencing these values (like in the example above) will work the same in all browsers. ### Rating Thresholds: The thresholds of each metric's "good", "needs improvement", and "poor" ratings are available as [`MetricRatingThresholds`](#metricratingthresholds). Example: ```ts import {CLSThresholds, INPThresholds, LCPThresholds} from 'web-vitals'; console.log(CLSThresholds); // [ 0.1, 0.25 ] console.log(INPThresholds); // [ 200, 500 ] console.log(LCPThresholds); // [ 2500, 4000 ] ``` > [!NOTE] > It's typically not necessary (or recommended) to manually calculate metric value ratings using these thresholds. Use the [`Metric['rating']`](#metric) instead. ### Attribution: In the [attribution build](#attribution-build) each of the metric functions has two primary differences from their standard build counterparts: 1. Their callback is invoked with a `MetricWithAttribution` objects instead of a `Metric` object. Each `MetricWithAttribution` extends the `Metric` object and adds an additional `attribution` object, which contains potentially-helpful debugging information that can be sent along with the metric values for the current page visit in order to help identify issues happening to real-users in the field. 2. They accept an `AttributionReportOpts` objects instead of a `ReportOpts` object. The `AttributionReportOpts` object supports an additional, optional, `generateTarget()` function that lets developers customize how DOM elements are stringified for reporting purposes. When passed, the return value of the `generateTarget()` function will be used for any "target" properties in the following attribution objects: [`CLSAttribution`](#CLSAttribution), [`INPAttribution`](#INPAttribution), and [`LCPAttribution`](#LCPAttribution). If `null` or `undefined` is returned by the `generateTarget()` function, or no function is given, then the default selector function will be used. ```ts interface AttributionReportOpts extends ReportOpts { generateTarget?: (el: Node | null) => string | null | undefined; } ``` For example, if a web page has unique `data-name` attribute on many elements, you may prefer to use those over the built-in selector-style strings that are generated by default. ```js function customGenerateTarget(el) { if (el.dataset.name) { return el.dataset.name; } // Otherwise use default selector function } onLCP(sendToAnalytics, {generateTarget: customGenerateTarget}); ``` The next sections document the shape of the `attribution` object for each of the metrics: #### `CLSAttribution` ```ts interface CLSAttribution { /** * By default, a selector identifying the first element (in document order) * that shifted when the single largest layout shift that contributed to the * page's CLS score occurred. If the `generateTarget` configuration option * was passed, then this will instead be the return value of that function, * falling back to the default if that returns null or undefined. */ largestShiftTarget?: string; /** * The time when the single largest layout shift contributing to the page's * CLS score occurred. */ largestShiftTime?: DOMHighResTimeStamp; /** * The layout shift score of the single largest layout shift contributing to * the page's CLS score. */ largestShiftValue?: number; /** * The `LayoutShiftEntry` representing the single largest layout shift * contributing to the page's CLS score. (Useful when you need more than just * `largestShiftTarget`, `largestShiftTime`, and `largestShiftValue`). */ largestShiftEntry?: LayoutShift; /** * The first element source (in document order) among the `sources` list * of the `largestShiftEntry` object. (Also useful when you need more than * just `largestShiftTarget`, `largestShiftTime`, and `largestShiftValue`). */ largestShiftSource?: LayoutShiftAttribution; /** * The loading state of the document at the time when the largest layout * shift contribution to the page's CLS score occurred (see `LoadState` * for details). */ loadState?: LoadState; } ``` #### `FCPAttribution` ```ts interface FCPAttribution { /** * The time from when the user initiates loading the page until when the * browser receives the first byte of the response (a.k.a. TTFB). */ timeToFirstByte: number; /** * The delta between TTFB and the first contentful paint (FCP). */ firstByteToFCP: number; /** * The loading state of the document at the time when FCP `occurred (see * `LoadState` for details). Ideally, documents can paint before they finish * loading (e.g. the `loading` or `dom-interactive` phases). */ loadState: LoadState; /** * The `PerformancePaintTiming` entry corresponding to FCP. */ fcpEntry?: PerformancePaintTiming; /** * The `navigation` entry of the current page, which is useful for diagnosing * general page load issues. This can be used to access `serverTiming` for example: * navigationEntry?.serverTiming */ navigationEntry?: PerformanceNavigationTiming; } ``` #### `INPAttribution` ```ts interface INPAttribution { /** * By default, a selector identifying the element that the user first * interacted with as part of the frame where the INP candidate interaction * occurred. If this value is an empty string, that generally means the * element was removed from the DOM after the interaction. If the * `generateTarget` configuration option was passed, then this will instead * be the return value of that function, falling back to the default if that * returns null or undefined. */ interactionTarget: string; /** * The time when the user first interacted during the frame where the INP * candidate interaction occurred (if more than one interaction occurred * within the frame, only the first time is reported). */ interactionTime: DOMHighResTimeStamp; /** * The type of interaction, based on the event type of the `event` entry * that corresponds to the interaction (i.e. the first `event` entry * containing an `interactionId` dispatched in a given animation frame). * For "pointerdown", "pointerup", or "click" events this will be "pointer", * and for "keydown" or "keyup" events this will be "keyboard". */ interactionType: 'pointer' | 'keyboard'; /** * The best-guess timestamp of the next paint after the interaction. * In general, this timestamp is the same as the `startTime + duration` of * the event timing entry. However, since duration values are rounded to the * nearest 8ms (and can be rounded down), this value is clamped to always be * reported after the processing times. */ nextPaintTime: DOMHighResTimeStamp; /** * An array of Event Timing entries that were processed within the same * animation frame as the INP candidate interaction. * Note this is capped to a max of 5 entries (the first 4 + the last one). */ processedEventEntries: PerformanceEventTiming[]; /** * The time from when the user interacted with the page until when the * browser was first able to start processing event listeners for that * interaction. This time captures the delay before event processing can * begin due to the main thread being busy with other work. */ inputDelay: number; /** * The time from when the first event listener started running in response to * the user interaction until when all event listener processing has finished. */ processingDuration: number; /** * The time from when the browser finished processing all event listeners for * the user interaction until the next frame is presented on the screen and * visible to the user. This time includes work on the main thread (such as * `requestAnimationFrame()` callbacks, `ResizeObserver` and * `IntersectionObserver` callbacks, and style/layout calculation) as well * as off-main-thread work (such as compositor, GPU, and raster work). */ presentationDelay: number; /** * The loading state of the document at the time when the interaction * corresponding to INP occurred (see `LoadState` for details). If the * interaction occurred while the document was loading and executing script * (e.g. usually in the `dom-interactive` phase) it can result in long delays. */ loadState: LoadState; /** * If the browser supports the Long Animation Frame API, this array will * include any `long-animation-frame` entries that intersect with the INP * candidate interaction's `startTime` and the `processingEnd` time of the * last event processed within that animation frame. If the browser does not * support the Long Animation Frame API or no `long-animation-frame` entries * are detected, this array will be empty. */ longAnimationFrameEntries: PerformanceLongAnimationFrameTiming[]; /** * Summary information about the longest script entry intersecting the INP * duration. Note, only script entries above 5 milliseconds are reported by * the Long Animation Frame API. */ longestScript?: INPLongestScriptSummary; /** * The total duration of Long Animation Frame scripts that intersect the INP * duration excluding any forced style and layout (that is included in * totalStyleAndLayout). Note, this is limited to scripts > 5 milliseconds. */ totalScriptDuration?: number; /** * The total style and layout duration from any Long Animation Frames * intersecting the INP interaction. This includes any end-of-frame style and * layout duration + any forced style and layout duration. */ totalStyleAndLayoutDuration?: number; /** * The off main-thread presentation delay from the end of the last Long * Animation Frame (where available) until the INP end point. */ totalPaintDuration?: number; /** * The total unattributed time not included in any of the previous totals. * This includes scripts < 5 milliseconds and other timings not attributed * by Long Animation Frame (including when a frame is < 50ms and so has no * Long Animation Frame). * When no Long Animation Frames are present this will be undefined, rather * than everything being unattributed to make it clearer when it's expected * to be small. */ totalUnattributedDuration?: number; } ``` #### `INPLongestScriptSummary` ```ts interface INPLongestScriptSummary { /** * The longest Long Animation Frame script entry that intersects the INP * interaction. */ entry: PerformanceScriptTiming; /** * The INP subpart where the longest script ran. */ subpart: 'input-delay' | 'processing-duration' | 'presentation-delay'; /** * The amount of time the longest script intersected the INP duration. */ intersectingDuration: number; } ``` #### `LCPAttribution` ```ts interface LCPAttribution { /** * By default, a selector identifying the element corresponding to the * largest contentful paint for the page. If the `generateTarget` * configuration option was passed, then this will instead be the return * value of that function, falling back to the default if that returns null * or undefined. */ target?: string; /** * The URL (if applicable) of the LCP image resource. If the LCP element * is a text node, this value will not be set. */ url?: string; /** * The time from when the user initiates loading the page until when the * browser receives the first byte of the response (a.k.a. TTFB). See * [Optimize LCP](https://web.dev/articles/optimize-lcp) for details. */ timeToFirstByte: number; /** * The delta between TTFB and when the browser starts loading the LCP * resource (if there is one, otherwise 0). See [Optimize * LCP](https://web.dev/articles/optimize-lcp) for details. */ resourceLoadDelay: number; /** * The total time it takes to load the LCP resource itself (if there is one, * otherwise 0). See [Optimize LCP](https://web.dev/articles/optimize-lcp) for * details. */ resourceLoadDuration: number; /** * The delta between when the LCP resource finishes loading until the LCP * element is fully rendered. See [Optimize * LCP](https://web.dev/articles/optimize-lcp) for details. */ elementRenderDelay: number; /** * The `navigation` entry of the current page, which is useful for diagnosing * general page load issues. This can be used to access `serverTiming` for example: * navigationEntry?.serverTiming */ navigationEntry?: PerformanceNavigationTiming; /** * The `resource` entry for the LCP resource (if applicable), which is useful * for diagnosing resource load issues. */ lcpResourceEntry?: PerformanceResourceTiming; /** * The `LargestContentfulPaint` entry corresponding to LCP. */ lcpEntry?: LargestContentfulPaint; } ``` #### `TTFBAttribution` ```ts interface TTFBAttribution { /** * The total time from when the user initiates loading the page to when the * page starts to handle the request. Large values here are typically due * to HTTP redirects, though other browser processing contributes to this * duration as well (so even without redirect it's generally not zero). */ waitingDuration: number; /** * The total time spent checking the HTTP cache for a match. For navigations * handled via service worker, this duration usually includes service worker * start-up time as well as time processing `fetch` event listeners, with * some exceptions, see: https://github.com/w3c/navigation-timing/issues/199 */ cacheDuration: number; /** * The total time to resolve the DNS for the requested domain. */ dnsDuration: number; /** * The total time to create the connection to the requested domain. */ connectionDuration: number; /** * The total time from when the request was sent until the first byte of the * response was received. This includes network time as well as server * processing time. */ requestDuration: number; /** * The `navigation` entry of the current page, which is useful for diagnosing * general page load issues. This can be used to access `serverTiming` for * example: navigationEntry?.serverTiming */ navigationEntry?: PerformanceNavigationTiming; } ``` ## Browser Support The `web-vitals` code is tested in Chrome, Firefox, and Safari. In addition, all JavaScript features used in the code are part of ([Baseline Widely Available](https://web.dev/baseline)), and thus should run without error in all versions of these browsers released within the last 30 months. However, some of the APIs required to capture these metrics (notable CLS) are currently only available in some browsers. The latest browser support for each function is as follows: - `onCLS()`: Chromium - `onFCP()`: Chromium, Firefox, Safari - `onINP()`: Chromium, Firefox, Safari - `onLCP()`: Chromium, Firefox, Safari - `onTTFB()`: Chromium, Firefox, Safari ## Limitations The `web-vitals` library is primarily a wrapper around the Web APIs that measure the Web Vitals metrics, which means the limitations of those APIs will mostly apply to this library as well. More details on these limitations is available in [this blog post](https://web.dev/articles/crux-and-rum-differences). The primary limitation of these APIs is they have no visibility into `