# @amplitude/plugin-web-vitals-browser

Latest version **1.2.2** (published 2026-09-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @amplitude/plugin-web-vitals-browser
pnpm add @amplitude/plugin-web-vitals-browser
yarn add @amplitude/plugin-web-vitals-browser
bun add @amplitude/plugin-web-vitals-browser
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2026-09-29 |
| First published | 2025-05-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 258.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 181 |
| Author | Amplitude Inc |
| Maintainers | curtisbliu, kelson.warner, sdk.dev, eric_amplitude, daniel-graham-amplitude, jjwang123 |

## Links

- npm: https://www.npmjs.com/package/@amplitude/plugin-web-vitals-browser
- Repository: https://github.com/amplitude/Amplitude-TypeScript
- Issues: https://github.com/amplitude/Amplitude-TypeScript/issues
- npm.io page: https://npm.io/package/@amplitude/plugin-web-vitals-browser

## Dependencies (3)

- [tslib](https://npm.io/package/tslib.md) ^2.4.1
- [web-vitals](https://npm.io/package/web-vitals.md) 6.2.1
- [@amplitude/analytics-core](https://npm.io/package/@amplitude/analytics-core.md) 2.59.0

## Recent versions

- 1.2.2 (latest) — 2026-09-29
- 1.1.49-video-analytics-5.0 (video-analytics-5) — 2026-09-22
- 1.1.48-video-analytics-4.0 (video-analytics-4) — 2026-09-17
- 1.1.47-video-analytics-2.0 (video-analytics-2) — 2026-09-09
- 1.1.45-video-analytics.0 (video-analytics) — 2026-07-31
- 1.1.36-featelement-selector-v1.0 (featelement-selector-v1) — 2026-06-15
- 1.1.35-SR-4497-custom-transport-hooks.0 (SR-4497-custom-transport-hooks) — 2026-06-09
- 1.1.34-sr-perf-reliability-rc.0 (sr-perf-reliability-rc) — 2026-06-05
- 1.1.34-sr-4646-rc.0 (sr-4646-rc) — 2026-06-03
- 1.1.33-sr-idb-multitab-test-rc.0 (sr-idb-multitab-test-rc) — 2026-05-04
- 1.1.30-sr-3531-rc-2.0 (sr-3531-rc-2) — 2026-04-20
- 1.1.28-SR-3115-rc2.0 (SR-3115-rc2) — 2026-04-08
- 1.1.28-SR-3115-rc1.0 (SR-3115-rc1) — 2026-04-03
- 1.1.28-SR-3115.0 (SR-3115) — 2026-04-03
- 1.1.19-SR-2728.0 (SR-2728) — 2026-03-12
- … 102 more at https://npm.io/package/@amplitude/plugin-web-vitals-browser/versions

## README

<p align="center">
  <a href="https://amplitude.com" target="_blank" align="center">
    <img src="https://static.amplitude.com/lightning/46c85bfd91905de8047f1ee65c7c93d6fa9ee6ea/static/media/amplitude-logo-with-text.4fb9e463.svg" width="280">
  </a>
  <br />
</p>

# @amplitude/plugin-web-vitals-browser (beta)
**This plugin is in beta at the moment, naming and interface might change in the future.**

Autocaptures [web-vitals](https://www.npmjs.com/package/web-vitals) metrics (INP, LCP, FCP, CLS)

## Installation

This package is published on NPM registry and is available to be installed using npm and yarn.

```sh
# npm
npm install @amplitude/plugin-web-vitals-browser@beta

# yarn
yarn add @amplitude/plugin-web-vitals-browser@beta
```

## Usage

```typescript
import * as amplitude from '@amplitude/analytics-browser';
import { webVitalsPlugin } from '@amplitude/plugin-web-vitals-browser';
```

### 2. Instantiate the plugin

```typescript
const plugin = webVitalsPlugin();
```

#### Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `reportSoftNav` | `boolean` | `false` | Also report web vitals for soft navigations, not only for the initial page load. |

##### `reportSoftNav`

Single page applications update the URL and history without a full page navigation, so by default
Core Web Vitals are only measured once, for the initial page load. With `reportSoftNav` enabled,
LCP, FCP, INP, CLS and TTFB are also measured per
[soft navigation](https://github.com/WICG/soft-navigations), and one `[Amplitude] Web Vitals` event
is sent per navigation, with the page properties of the URL the metrics belong to. Metrics measured
for a soft navigation have a `navigationType` of `soft-navigation`.

```typescript
const plugin = webVitalsPlugin({ reportSoftNav: true });
```

This requires browser support for the Soft Navigations API (Chromium 151+). In browsers without it,
reporting is unchanged from the default behavior.

Note that enabling this also changes how the initial page load is measured: its metrics are
finalized once the first soft navigation occurs, rather than when the page is hidden.

When using the Browser SDK's autocapture, the same option can be set through
`autocapture.webVitals`:

```typescript
amplitude.init('API_KEY', {
  autocapture: {
    webVitals: { reportSoftNav: true },
  },
});
```

### 3. Install plugin to Amplitude SDK

```typescript
amplitude.add(plugin);
```

### 4. Initialize Amplitude SDK

```typescript
amplitude.init('API_KEY');
```

---
_Source: https://npm.io/package/@amplitude/plugin-web-vitals-browser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._