NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm, #4153 most downloaded on npm
Type definitions for the PostHog JavaScript SDK
Latest stable
1.425.1
Last release 6 days ago
13 Nov 2026
Ships on a steady schedule
a new release about every 9 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
10 months old
280 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
isFeatureEnabled(key, { defaultValue: false }) now returns the given default when the flag has no value — flags not loaded yet, or no flag with that k
#4222 0f2407b Thanks @turnipdabeets! - feat: add a default-value option to isFeatureEnabled
isFeatureEnabled(key, { defaultValue: false }) now returns the given default when the flag has no value — flags not loaded yet, or no flag with that key — and the return type narrows to boolean. The option name is the same in posthog-js, posthog-js-lite, and posthog-react-native. Without defaultValue, behavior is unchanged: boolean | undefined. (2026-07-22)
## 1.397.1 ### Patch Changes - #4198 `fbfc84f` Thanks @pauldambra! - feat: make the pending session recording trigger buffer interval configurable (20
fbfc84f Thanks @pauldambra! - feat: make the pending session recording trigger buffer interval configurable
(2026-07-20)Your coding agent can read these notes before it upgrades. Set up the MCP server →
## 1.397.0 ### Minor Changes - #4149 `607bf54` Thanks @pauldambra! - Add dead swipe detection to dead clicks autocapture. When dead clicks autocapture
607bf54 Thanks @pauldambra! - Add dead swipe detection to dead clicks autocapture. When dead clicks autocapture is enabled, touch swipe gestures that produce no observable screen change (no scroll, mutation, selection or visibility change) are now captured as $dead_swipe events, surfacing failed navigations on touch devices. Configurable via capture_dead_swipes (default true) and swipe_threshold_px (default 30) on the capture_dead_clicks config. Swipes over surfaces whose response cannot be observed (canvas, video and other media elements under the finger) are skipped, and captures are limited per page load via max_dead_swipes_per_page_load (default 10).
(2026-07-16)$feature_flag_called events now carry a $feature_flag_has_experiment boolean sourced from the server's has_experiment flag metadata (the /flags?v=2 re
#4159 fad6d9a Thanks @haacked! - add $feature_flag_has_experiment to $feature_flag_called events
$feature_flag_called events now carry a $feature_flag_has_experiment boolean sourced from the server's has_experiment flag metadata (the /flags?v=2 response for remote evaluation, the /api/feature_flag/local_evaluation definitions for posthog-node local evaluation). The property is only sent when the server explicitly reports has_experiment; it is omitted entirely when the value is unknown (older servers, missing metadata, bootstrapped or locally injected flags). (2026-07-16)
## 1.395.0 ### Minor Changes - #4129 `800af7c` Thanks @pauldambra! - feat: add session_recording.attributeFilter option that passes an attribute allow
800af7c Thanks @pauldambra! - feat: add session_recording.attributeFilter option that passes an attribute allowlist through to the native MutationObserver, so mutations to unlisted attributes (e.g. animation-driven inline style churn) never cost recording CPU (port of upstream rrweb #1873)
(2026-07-15)## 1.394.0 ### Minor Changes - #4101 `dc2aa5b` Thanks @posthog! - Normalize the error tracking rate-limiter config to first-class options. The browser
dc2aa5b Thanks @posthog! - Normalize the error tracking rate-limiter config to first-class options. The browser SDK now reads exceptionRateLimiterRefillRate / exceptionRateLimiterBucketSize on error_tracking, with the previous double-underscore __exceptionRateLimiterRefillRate / __exceptionRateLimiterBucketSize options deprecated but still honoured as a fallback. The option shape (ExceptionRateLimiterConfig) and default-resolution logic (resolveExceptionRateLimiterConfig) now live in @posthog/core and are shared between the browser and Node SDKs.
(2026-07-14)A statsd-style pre-aggregating metrics client for the PostHog Metrics product (alpha). Samples are folded into per-series aggregates in memory (counts
#4115 86bb3a5 Thanks @DanielVisca! - add the posthog.metrics API (count, gauge, histogram) — alpha
A statsd-style pre-aggregating metrics client for the PostHog Metrics product (alpha). Samples are folded into per-series aggregates in memory (counts sum, gauges keep the last value, histograms accumulate buckets) and flushed periodically as OTLP/JSON to /i/v1/metrics — one data point per series per flush window, no matter how many calls. No OpenTelemetry SDK setup required:
posthog.metrics.count('orders_created', 1)
posthog.metrics.gauge('active_connections', 42)
posthog.metrics.histogram('api_latency', 187, { unit: 'ms' })
Configure via metrics: { serviceName, environment, flushIntervalMs, maxSeriesPerFlush, beforeSend, ... }. (2026-07-08)
## 1.392.1 ### Patch Changes - #4053 `45d1b36` Thanks @posthog! - feat(web): add a graceful shutdown() to the browser client for parity with posthog-n
45d1b36 Thanks @posthog! - feat(web): add a graceful shutdown() to the browser client for parity with posthog-node, so isomorphic teardown code (e.g. the Nuxt module) that calls posthog.shutdown() on the client no longer throws TypeError: shutdown is not a function. It best-effort flushes the queued events and always resolves.
(2026-07-03)### Minor Changes - #3987 `74cc6bb` Thanks @TueHaulund! - Add a get_current_url config option that overrides the URL used for client-side URL targetin
74cc6bb Thanks @TueHaulund! - Add a get_current_url config option that overrides the URL used for client-side URL targeting — session replay URL triggers, the session replay URL blocklist, survey URL display conditions, product tour URL conditions, web experiment URL conditions, and autocapture URL allow/ignore lists. These match against window.location.href directly, which does not reflect a $current_url rewritten in before_send. Apps where the browser URL is not meaningful for targeting (e.g. Electron/desktop builds served from a generated host) can now return the logical URL to match against. Defaults to window.location.href when not set.
(2026-06-29)### Patch Changes - #3919 `99bad9c` Thanks @pauldambra! - Session replay network capture: add an opt-in streaming reader for request/response bodies t
99bad9c Thanks @pauldambra! - Session replay network capture: add an opt-in streaming reader for request/response bodies that stops at the payload size limit instead of buffering the whole body and then discarding it — bounding memory and pre-request latency when a body is very large. It reads only a clone of the body, so it never consumes the stream the page itself reads, and always resolves (never rejects) into the page's fetch. Off by default; enabled for defaults: '2026-06-25' and settable directly via session_recording.streamNetworkBody.
(2026-06-24)If you only want to capture some hashes, leave hash capture enabled and use before_send to remove or redact sensitive hash values before events are se
#3921 c28b161 Thanks @marandaneto! - Add disable_capture_url_hashes to strip URL fragments from automatically captured URLs. It is disabled by default for backwards compatibility, and enabled automatically when config.defaults is '2026-06-25' or later. Enabling it (either explicitly or via the '2026-06-25' defaults) is a breaking behavior change for SPAs that rely on URL hashes for routing or analytics, because hash-based routes will be collapsed to the same URL without the fragment in fields such as $current_url, $initial_current_url, $session_entry_url, autocapture $elements[*].attr__href, $external_click_url, replay href URLs, heatmaps, web vitals $current_url, logs url.full, conversations current_url/request_url, or Next.js Pages Router $pageview $current_url.
If you only want to capture some hashes, leave hash capture enabled and use before_send to remove or redact sensitive hash values before events are sent. (2026-06-23)
### Patch Changes - #3903 `6b21f77` Thanks @marandaneto! - Validate custom event UUID overrides and generate new UUIDs when invalid. (2026-06-19)
6b21f77 Thanks @marandaneto! - Validate custom event UUID overrides and generate new UUIDs when invalid.
(2026-06-19)Adds session_recording.canvasCapture.resolutionScale - a (0, 1] fraction of the canvas display size to capture replay frames at. The captured bitmap i
#3885 5392a55 Thanks @pauldambra! - feat(replay): capture canvas at reduced resolution
Adds session_recording.canvasCapture.resolutionScale - a (0, 1] fraction of the canvas display size to capture replay frames at. The captured bitmap is downscaled (pixel-area savings are quadratic) while the canvas's true display size is still recorded, so playback stretches the smaller frame back to the correct dimensions and aspect ratio - only sharpness drops, never layout. It defaults to 1 (full resolution, matching today's behaviour), and the latest defaults bundle (2026-05-30) opts new installs into 0.6.
The canvas's true display size travels with each frame through the encode worker (as required message fields), so the encoded reply is always drawn back to the correct dimensions — no per-canvas state is retained on the main thread, and downscaling can never mislabel a canvas's dimensions. At full resolution the captured pixels are unchanged (the quality resampling hint is only applied when actually downscaling); the emitted drawImage now always uses the explicit destination-size form, which is pixel-equivalent on replay.
Mechanically, @posthog/rrweb's canvas FPS-snapshot observer takes an optional canvasResolutionScale record option and downscales each captured frame accordingly. (2026-06-19)
`js posthog.init(" ", { logs: { beforeSend: (log) => { // return null to drop the log, or return the (optionally modified) log to keep it if (log.body
#3869 81b79fb Thanks @turnipdabeets! - Add a beforeSend option to the logs config, so you can inspect, redact, or drop log records before they're sent:
posthog.init("<token>", {
logs: {
beforeSend: (log) => {
// return null to drop the log, or return the (optionally modified) log to keep it
if (log.body.includes("password")) {
return null;
}
return log;
},
},
});
beforeSend accepts a single function or an array of functions (applied left to right); returning null from any of them drops the record. It runs for logs sent via both posthog.captureLog() and posthog.logger.*. (2026-06-17)
### Minor Changes - #3865 `b469830` Thanks @turnipdabeets! - The browser's programmatic logs API (posthog.captureLog() / posthog.logger.*) now runs th
b469830 Thanks @turnipdabeets! - The browser's programmatic logs API (posthog.captureLog() / posthog.logger.*) now runs through the shared @posthog/core logs pipeline that React Native already uses — no change to the public API or existing behavior. Log delivery is more resilient as a result: oversized batches are split automatically, failed sends retry with exponential backoff, and delivery resumes when the browser comes back online.
(2026-06-17)### Minor Changes - #3863 `b6bc9be` Thanks @marandaneto! - Add autocapture-only CSS selector opt-outs for web interactions. (2026-06-17)
b6bc9be Thanks @marandaneto! - Add autocapture-only CSS selector opt-outs for web interactions.
(2026-06-17)### Minor Changes - #3709 `c6c163a` Thanks @posthog! - Add unsetPersonProperties() to remove person properties, the counterpart to setPersonProperties
c6c163a Thanks @posthog! - Add unsetPersonProperties() to remove person properties, the counterpart to setPersonProperties(). Previously the only way to unset a person property was to hand-pass a $unset array inside a capture() call.
(2026-06-16)c9c7df1 Thanks @marandaneto! - Add $unset to capture options and pass it through in browser capture payloads.
(2026-06-16)### Patch Changes - #3837 `29bf8e3` Thanks @marandaneto! - Add missing bugs metadata to package manifests. (2026-06-15)
29bf8e3 Thanks @marandaneto! - Add missing bugs metadata to package manifests.
(2026-06-15)A session now rotates only when every tab has been idle past the timeout, rather than whenever a single background tab decides it is idle. On the acti
#3690 dbf2377 Thanks @pauldambra! - fix(sessionid): keep the session id stable across tabs
A session now rotates only when every tab has been idle past the timeout, rather than whenever a single background tab decides it is idle. On the active event path an idle tab re-reads the session id from storage before rotating: if a sibling tab kept the session alive it does not rotate, and if a sibling already rotated it adopts that id instead of minting a new one. This removes spurious cross-tab session fragmentation (inflated session counts, truncated session durations, split replays). When a sibling session is adopted, onSessionId handlers fire with changeReason.crossTabAdoption: true so session recording, pageview state, and session-scoped properties follow the new session. When persistence_save_debounce_ms > 0 (the 2026-05-30 default) the refresh reads only the session-id key so it cannot clobber a sibling's write.
Note: projects with significant multi-tab usage will see fewer but longer sessions after upgrading — this is a correction of previously over-counted sessions, not a traffic change. (2026-06-11)
Nothing published for this version
Nothing published for this version
Nothing published for this version
### Minor Changes - #3777 `f601c49` Thanks @dustinbyrne! - Promote external dependency script versioning to supported strict_script_versioning and ass
f601c49 Thanks @dustinbyrne! - Promote external dependency script versioning to supported strict_script_versioning and asset_host config options.
(2026-06-10)c11794d Thanks @dustinbyrne! - Reload feature flags by default when resetting person properties for flags.
(2026-06-10)### Patch Changes - #3791 `2d21ada` Thanks @marandaneto! - Deprecate __preview_disable_beacon in favor of disable_beacon and mark __preview_disable_xh
2d21ada Thanks @marandaneto! - Deprecate __preview_disable_beacon in favor of disable_beacon and mark __preview_disable_xhr_credentials as a no-op.
(2026-06-10)### Patch Changes - #3789 `d9462b3` Thanks @marandaneto! - Deprecate __preview_eager_load_replay as a no-op now that session replay lazy loading is th
d9462b3 Thanks @marandaneto! - Deprecate __preview_eager_load_replay as a no-op now that session replay lazy loading is the default.
(2026-06-10)Nothing published for this version
Note: $browser_version for Google Search App is not comparable across platforms — iOS yields a version like 284.0 (from GSA/284.0.564099828) while And
#3782 0c2acb9 Thanks @pauldambra! - Detect the Google Search App (GSA) as its own $browser value (Google Search App) via the cross-platform GSA/ UA marker, instead of reporting the embedded webview as Mobile Safari (iOS) or Chrome (Android). Gated behind the new detect_google_search_app config option, which the 2026-05-30 config defaults opt into automatically — left off otherwise to keep existing browser attribution backwards-compatible.
Note: $browser_version for Google Search App is not comparable across platforms — iOS yields a version like 284.0 (from GSA/284.0.564099828) while Android yields a version like 14.21 (from GSA/14.21.20.28.arm64), since Google maintains separate versioning schemes for the two apps. Avoid building cross-platform version dashboards on $browser_version for this browser. (2026-06-10)
### Patch Changes - #3776 `783ba46` Thanks @marandaneto! - Deprecate the no-op __preview_flags_v2 browser SDK config option. The SDK already uses the
783ba46 Thanks @marandaneto! - Deprecate the no-op __preview_flags_v2 browser SDK config option. The SDK already uses the /flags/?v=2 endpoint by default.
(2026-06-09)Nothing published for this version
Nothing published for this version
### Minor Changes - #3771 `227c9b0` Thanks @dustinbyrne! - feat(persistence): add split_storage config option to store the feature-flag config cluster
#3771 227c9b0 Thanks @dustinbyrne! - feat(persistence): add split_storage config option to store the feature-flag config cluster in its own localStorage entry (<name>__flags) instead of the single main persistence blob. This payload is large and changes rarely, so keeping it out of the main blob stops it riding on every high-frequency main-blob write and broadcasting on cross-tab storage events. Reads are unchanged: on load the entry is merged back into the in-memory props, and the old main-blob location is read once and migrated forward so upgrades never miss a cached flag. The split only applies when persistence resolves to localStorage / localStorage+cookie (it is pointless for memory / sessionStorage and impossible for cookie), and reset() / opt-out wipe every entry. Defaults to false for backwards compatibility; the new 2026-05-30 config default opts in automatically.
(2026-06-08)
#3727 393f9e2 Thanks @pauldambra! - feat(surveys): extend split_storage to also move the survey config ($surveys) out of the main persistence blob into its own <name>__surveys localStorage entry, on top of the feature-flag split. Surveys now stamp a $surveys_loaded_at freshness timestamp on every /surveys load — the survey analogue of $feature_flag_evaluated_at — so a stale __surveys entry can no longer win over a fresher survey payload written back into the main blob by a gate-off / older-SDK tab. With no timestamp on either side (migration leftover) the group entry still wins, so the migration path is unchanged. Same backend and reset() / opt-out semantics as the flag split.
(2026-06-08)
Nothing published for this version
### Minor Changes - #3719 `a7bd828` Thanks @lricoy! - Add __preview_cookie_wins_on_conflict opt-in config to prefer cookie values over localStorage wh
Nothing published for this version
### Minor Changes - #3715 `2387084` Thanks @dustinbyrne! - Promote browser tracing header configuration to the public tracing_headers option while kee
2387084 Thanks @dustinbyrne! - Promote browser tracing header configuration to the public tracing_headers option while keeping addTracingHeaders and __add_tracing_headers as deprecated aliases.
(2026-06-04)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
### Minor Changes - #3688 `8181354` Thanks @pauldambra! - feat(persistence): add persistence_save_debounce_ms config option to coalesce rapid storage
8181354 Thanks @pauldambra! - feat(persistence): add persistence_save_debounce_ms config option to coalesce rapid storage saves into a single write. Setting a positive value debounces writes to localStorage/cookie by that window; the in-memory props object still updates synchronously so within-tab reads see the latest values immediately, and pending writes flush on beforeunload and pagehide so no state is lost on tab close. Cross-tab storage events are reduced proportionally to the debounce window. Defaults to 0 (no debouncing) for backwards compatibility. On pages that capture many events per second, 250 is a reasonable starting point. The new 2026-05-30 config default opts into persistence_save_debounce_ms: 250 automatically.
(2026-06-01)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
### Minor Changes - #3641 `2e1d5f4` Thanks @dustinbyrne! - Add flag_keys config to restrict browser feature flag remote evaluation to specific flag ke
2e1d5f4 Thanks @dustinbyrne! - Add flag_keys config to restrict browser feature flag remote evaluation to specific flag keys.
(2026-05-21)Nothing published for this version
### Patch Changes - #3607 `557b893` Thanks @eli-r-ph! - Enable $web_vitals reporting when cookieless mode is enabled (2026-05-20)
Nothing published for this version
Nothing published for this version
### Minor Changes - #3620 `594ea11` Thanks @pauldambra! - Dead clicks: add a .ph-no-deadclick CSS class (and capture_dead_clicks.css_selector_ignoreli
594ea11 Thanks @pauldambra! - Dead clicks: add a .ph-no-deadclick CSS class (and capture_dead_clicks.css_selector_ignorelist config option) to exclude specific elements from dead-click detection without affecting autocapture, session replay, or heatmaps. Mirrors the existing .ph-no-rageclick pattern.
(2026-05-18)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per month.