Update JS SDK defaults config date from 2025-05-24 to 2025-11-30 (#13880)

Copilot · pauldambra · gewenyu99 · web-flow · commit b37cbe41013c · 2025-12-01T11:41:35.000Z
* Initial plan * Update JS SDK defaults config date from 2025-05-24 to 2025-11-30 Co-authored-by: pauldambra <984817+pauldambra@users.noreply.github.com> * Apply suggestion from @pauldambra * Add 2025-11-30 defaults documentation for rageclick.content_ignorelist and session_recording.strictMinimumDuration Co-authored-by: pauldambra <984817+pauldambra@users.noreply.github.com> * Update contents/docs/libraries/js/config.mdx Co-authored-by: Vincent (Wen Yu) Ge <29069505+gewenyu99@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: pauldambra <984817+pauldambra@users.noreply.github.com> Co-authored-by: Paul D'Ambra <paul@posthog.com> Co-authored-by: Vincent (Wen Yu) Ge <29069505+gewenyu99@users.noreply.github.com>
diff --git a/contents/docs/error-tracking/installation/web.mdx b/contents/docs/error-tracking/installation/web.mdx
@@ -120,7 +120,7 @@ if (!window.location.host.includes('127.0.0.1') && !window.location.host.include
 <details>
 <summary>What is the `defaults` option?</summary>
 
-The `defaults` is a date, such as `2025-05-24`, for a configuration snapshot used as defaults to initialize PostHog. This default is overridden when you explicitly set a value for any of the options.
+The `defaults` is a date, such as `2025-11-30`, for a configuration snapshot used as defaults to initialize PostHog. This default is overridden when you explicitly set a value for any of the options.
 
 </details>
 
diff --git a/contents/docs/integrate/_snippets/install-web.mdx b/contents/docs/integrate/_snippets/install-web.mdx
@@ -79,6 +79,6 @@ if (!window.location.host.includes('127.0.0.1') && !window.location.host.include
 <details>
 <summary>What is the `defaults` option?</summary>
 
-The `defaults` is a date, such as `2025-05-24`, for a configuration snapshot used as defaults to initialize PostHog. This default is overridden when you explicitly set a value for any of the options.
+The `defaults` is a date, such as `2025-11-30`, for a configuration snapshot used as defaults to initialize PostHog. This default is overridden when you explicitly set a value for any of the options.
 
 </details>
diff --git a/contents/docs/libraries/angular.mdx b/contents/docs/libraries/angular.mdx
@@ -33,7 +33,7 @@ import AngularInstall from "../integrate/_snippets/install-angular.mdx"
 
 ## Tracking pageviews
 
-PostHog automatically tracks your pageviews by hooking up to the browser's `navigator` API as long as you initialize PostHog with the `defaults` config option set after `2025-05-24`.
+PostHog automatically tracks your pageviews by hooking up to the browser's `navigator` API as long as you initialize PostHog with the `defaults` config option set after `2025-11-30`.
 
 ## Capture custom events
 
diff --git a/contents/docs/libraries/js/config.mdx b/contents/docs/libraries/js/config.mdx
@@ -44,7 +44,7 @@ Some of the most relevant options are:
 | `capture_dead_clicks`<br/><br/>**Type:** Boolean<br/>**Default:** `true`                                                                                                                  | Determines if PostHog should automatically capture dead click events.                                                                                                                                                                                                                                          |
 | `cross_subdomain_cookie`<br/><br/>**Type:** Boolean<br/>**Default:** `true`                                                                                                               | Determines if cookie should be set on the top level domain (example.com). If `posthog-js` is loaded on a subdomain (`test.example.com`), _and_ `cross_subdomain_cookie` is set to false, it'll set the cookie on the subdomain only (`test.example.com`).                                                      |
 | [`custom_blocked_useragents`](/docs/libraries/js/features#blocking-bad-actors)<br/><br/>**Type:** Array<br/>**Default:** `[]`                                                             | A list of user agents to block when sending events.                                                                                                                                                                                                                                                            |
-| `defaults`<br/><br/>**Type:** String<br/>**Default:** `unset`                                                                                                                             | Whether we should use the most recent set of defaults or the legacy ones. Will use the legacy ones by default, set to `'<ph_posthog_js_defaults>'` to use the most recent defaults.                                                                                                                            |
+| `defaults`<br/><br/>**Type:** String<br/>**Default:** `unset`                                                                                                                             | Configuration defaults for breaking changes. When set to a specific date, enables new default behaviors that were introduced on that date. Set to `'<ph_posthog_js_defaults>'` to use the most recent defaults. <br/><br/> Options: `'unset'` (legacy behaviors), `'2025-05-24'` (`capture_pageview` defaults to `'history_change'`), `'2025-11-30'` (includes 2025-05-24 changes plus `session_recording.strictMinimumDuration` and `rageclick.content_ignorelist` enabled by default). |
 | `disable_persistence`<br/><br/>**Type:** Boolean<br/>**Default:** `false`                                                                                                                 | Disable persisting user data across pages. This will disable cookies, session storage and local storage.                                                                                                                                                                                                       |
 | `disable_surveys`<br/><br/>**Type:** Boolean<br/>**Default:** `false`                                                                                                                     | Determines if surveys script should load which controls whether they show up for users, and whether requests for API surveys return valid data                                                                                                                                                                 |
 | `disable_session_recording`<br/><br/>**Type:** Boolean<br/>**Default:** `false`                                                                                                           | Determines if users should be opted out of session recording.                                                                                                                                                                                                                                                  |
@@ -63,10 +63,10 @@ Some of the most relevant options are:
 | `property_denylist`<br/><br/>**Type:** Array<br/>**Default:** `[]` | A list of properties that should never be sent with `capture` calls. |
 | `person_profiles`<br/><br/>**Type:** Enum: `always`, `identified_only`<br/>**Default:** `identified_only` | Set whether events should capture identified events and process person profiles. |
 | `rate_limiting`<br/><br/>**Type:** Object<br/>**Default:** `{ events_per_second: 10, events_burst_limit: events_per_second * 10 }` | Controls event rate limiting to help you avoid accidentally sending too many events. `events_per_second` determines how many events can be sent per second on average (default: 10). `events_burst_limit` sets the maximum events that can be sent at once (default: 10 times the `events_per_second` value). |
-| `session_recording`<br/><br/>**Type:** Object<br/>**Default:** [See here.](https://github.com/PostHog/posthog-js/blob/96fa9339b9c553a1c69ec5db9d282f31a65a1c25/src/posthog-core.js#L1032) | Configuration options for recordings. More details [found here](/docs/session-replay/manual). |
+| `session_recording`<br/><br/>**Type:** Object<br/>**Default:** [See here.](https://github.com/PostHog/posthog-js/blob/96fa9339b9c553a1c69ec5db9d282f31a65a1c25/src/posthog-core.js#L1032) | Configuration options for recordings. More details [found here](/docs/session-replay/manual). When `defaults: '2025-11-30'` or later is set, `strictMinimumDuration` is enabled by default, which checks the minimum duration against actual buffer data rather than session duration. |
 | `session_idle_timeout_seconds`<br/><br/>**Type:** Integer<br/>**Default:** `1800` | The maximum amount of time a session can be inactive before it is split into a new session. |
 | `xhr_headers`<br/><br/>**Type:** Object<br/>**Default:** `{}` | Any additional headers you wish to pass with the XHR requests to the PostHog API. |
-| `rageclick`<br/><br/>**Type:** Boolean or RageclickConfig<br/>**Default:** `true` | Determines if PostHog should automatically capture rage click events when users rapidly click on non-responsive elements. [See below for `RageclickConfig`](#configuring-rageclick). |
+| `rageclick`<br/><br/>**Type:** Boolean or RageclickConfig<br/>**Default:** `true` | Determines if PostHog should automatically capture rage click events when users rapidly click on non-responsive elements. When `defaults: '2025-11-30'` or later is set, `content_ignorelist` is enabled by default to ignore elements with navigation-related text. [See below for `RageclickConfig`](#configuring-rageclick). |
 
 
 
@@ -92,6 +92,7 @@ But if you need more control, we also provide a `rageclick` config that takes an
 | Attribute | Description |
 |-----------|-------------|
 | `css_selector_ignorelist`<br/><br/>**Type:** Array of Strings<br/>**Default:** `undefined` | List of CSS selectors to ignore rage clicks on, e.g. `['.carousel-button', '.next-button']`. Elements matching these selectors (or their parents) won't trigger rage click events. An empty array disables rage click events all together. Providing any value overrides the defaults, so PostHog will *only* ignore the selectors you explicitly provide in the array. |
+| `content_ignorelist`<br/><br/>**Type:** Boolean or Array of Strings<br/>**Default:** `true` when `defaults: '2025-11-30'` or later | Excludes elements from rage click tracking based on their text content or aria-label. When `true`, uses default keywords ['next', 'previous', 'prev', '>', '<']. When set to an array of strings (max 10 items), uses custom keywords. Set to `false` to disable content-based exclusion. Useful for preventing false positives on navigation elements. |
 
 ## Advanced configuration
 
diff --git a/contents/docs/libraries/next-js/index.mdx b/contents/docs/libraries/next-js/index.mdx
@@ -187,12 +187,12 @@ The problem with this is that it can cause a [hydration and/or mismatch error](h
 
 ### Why did the pageview component need a `useEffect`?
 
-Before updating the JavaScript Web SDK's default behavior when capturing pageviews (`'2025-05-24'`), we suggested using a `useEffect` hook to capture pageviews. This is because it's the simplest way to accurately capture pageviews. Other approaches include:
+Before updating the JavaScript Web SDK's default behavior when capturing pageviews (`'2025-11-30'`), we suggested using a `useEffect` hook to capture pageviews. This is because it's the simplest way to accurately capture pageviews. Other approaches include:
 
 1. Not using a `useEffect` hook, but this might lead to duplicate page views being tracked if the component re-renders for reasons other than navigation. It might work depending on your implementation.
 2. Using `window.navigation` to track pageviews, but this approach is more complex and is [not supported](https://developer.mozilla.org/en-US/docs/Web/API/Window/navigation) in all browsers.
 
-> **Note:** This approach of manually capturing pageviews is no longer recommended. We recommend using `defaults: '2025-05-24'` or `capture_pageview: 'history_change'` instead, which automatically handles both `$pageview` and `$pageleave` events.
+> **Note:** This approach of manually capturing pageviews is no longer recommended. We recommend using `defaults: '2025-11-30'` or `capture_pageview: 'history_change'` instead, which automatically handles both `$pageview` and `$pageleave` events.
 >
 > If you're still capturing pageviews manually, you should also capture `$pageleave` events to track important engagement metrics like time on page (`$prev_pageview_duration`) and scroll depth (`$prev_pageview_max_scroll_percentage`). To do this, set up a listener on window unload (similar to [how PostHog does it](https://github.com/PostHog/posthog-js/blob/main/packages/browser/src/posthog-core.ts#L644-L646)):
 >
diff --git a/contents/handbook/content/docs-style-guide.mdx b/contents/handbook/content/docs-style-guide.mdx
@@ -340,7 +340,7 @@ You can use magic placeholders to replace the project API key, project name, app
 | `<ph_app_host>`            | Your PostHog instance URL     | `<ph_app_host>`                                 |
 | `<ph_client_api_host>`     | Your PostHog client API host  | `https://us.i.posthog.com`                      |
 | `<ph_region>`              | Your PostHog region (us/eu)   | `<ph_region>`                                   |
-| `<ph_posthog_js_defaults>` | Default values for posthog-js | `2025-05-24`                                    |
+| `<ph_posthog_js_defaults>` | Default values for posthog-js | `2025-11-30`                                    |
 | `<ph_proxy_path>`          | Your proxy path               | `relay-XXXX` (last 4 digits of project API key) |
 
 You can use these placeholders in the code block like this:
diff --git a/contents/tutorials/event-tracking-guide.md b/contents/tutorials/event-tracking-guide.md
@@ -41,7 +41,7 @@ Although autocapture is a great way to get started, it can be limiting for more
 
 3. **Customization**. Although it is possible to [add properties to autocapture](/docs/product-analytics/autocapture#capturing-additional-properties-in-autocapture-events), getting exactly the data you want at the exact moment you want requires customization.
 
-4. **Pageviews rely on page loads**. Pageview captures rely on page load events. This means they don't work well with [single-page apps (SPAs)](/tutorials/single-page-app-pageviews). To fix this, you can rely on the [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to capture pageviews by setting the `capture_pageview` configuration option to `history_change` or by using the most recent `defaults: '2025-05-24'`.
+4. **Pageviews rely on page loads**. Pageview captures rely on page load events. This means they don't work well with [single-page apps (SPAs)](/tutorials/single-page-app-pageviews). To fix this, you can rely on the [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to capture pageviews by setting the `capture_pageview` configuration option to `history_change` or by using the most recent `defaults: '2025-11-30'`.
 
 ## Setting up custom events
 
diff --git a/contents/tutorials/nextjs-analytics.md b/contents/tutorials/nextjs-analytics.md
@@ -96,7 +96,7 @@ import posthog from 'posthog-js'
 
 posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
   api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
-  defaults: '2025-05-24',
+  defaults: '2025-11-30',
 });
 ```
 
diff --git a/contents/tutorials/nextjs-pages-analytics.md b/contents/tutorials/nextjs-pages-analytics.md
@@ -295,7 +295,7 @@ import posthog from 'posthog-js'
 
 posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
   api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
-  defaults: '2025-05-24'
+  defaults: '2025-11-30'
 });
 ```
 
diff --git a/contents/tutorials/single-page-app-pageviews.md b/contents/tutorials/single-page-app-pageviews.md
@@ -17,7 +17,7 @@ A single-page application (or SPA) dynamically loads content for new pages using
 
 PostHog's JavaScript Web SDK automatically captures pageview events on page load. The problem with SPAs is that **page loads don't happen beyond the initial one**. This means user navigation in your SPA isn't tracked.
 
-Luckily, you can opt-in to tracking this behavior by setting `defaults: '2025-05-24'` when initializing PostHog to use the most recent defaults. This default uses `capture_pageview: 'history_change'`, which captures SPA navigation using the browser [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) 
+Luckily, you can opt-in to tracking this behavior by setting `defaults: '2025-11-30'` when initializing PostHog to use the most recent defaults. This default uses `capture_pageview: 'history_change'`, which captures SPA navigation using the browser [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) 
 
 This tutorial shows you how to follow the recommended approach for the most popular SPA frameworks like [Next.js](#tracking-pageviews-in-nextjs-app-router), [Vue](#tracking-pageviews-in-vue), [Svelte](#tracking-pageviews-in-svelte), and [Angular](#tracking-pageviews-in-angular). 
 
diff --git a/src/components/CodeBlock/index.tsx b/src/components/CodeBlock/index.tsx
@@ -214,7 +214,7 @@ export const CodeBlock = ({
             .replace(/<ph_app_host>/g, removeQuotes(appHost) || '<ph_app_host>')
             .replace(/<ph_client_api_host>/g, removeQuotes(clientApiHost) || 'https://us.i.posthog.com')
             .replace(/<ph_region>/g, removeQuotes(region) || '<ph_region>')
-            .replace(/<ph_posthog_js_defaults>/g, '2025-05-24')
+            .replace(/<ph_posthog_js_defaults>/g, '2025-11-30')
             .replace(
                 /<ph_proxy_path>/g,
                 projectToken ? `relay-${removeQuotes(projectToken)?.slice(-4)}` : '<ph_proxy_path>'

Original file line number	Diff line number	Diff line change
`@@ -187,12 +187,12 @@ The problem with this is that it can cause a [hydration and/or mismatch error](h`
`187`	`187`
`188`	`188`	### Why did the pageview component need a `useEffect`?
`189`	`189`
`190`		-Before updating the JavaScript Web SDK's default behavior when capturing pageviews (`'2025-05-24'`), we suggested using a `useEffect` hook to capture pageviews. This is because it's the simplest way to accurately capture pageviews. Other approaches include:
	`190`	+Before updating the JavaScript Web SDK's default behavior when capturing pageviews (`'2025-11-30'`), we suggested using a `useEffect` hook to capture pageviews. This is because it's the simplest way to accurately capture pageviews. Other approaches include:
`191`	`191`
`192`	`192`	1. Not using a `useEffect` hook, but this might lead to duplicate page views being tracked if the component re-renders for reasons other than navigation. It might work depending on your implementation.
`193`	`193`	2. Using `window.navigation` to track pageviews, but this approach is more complex and is [not supported](https://developer.mozilla.org/en-US/docs/Web/API/Window/navigation) in all browsers.
`194`	`194`
`195`		-> Note: This approach of manually capturing pageviews is no longer recommended. We recommend using `defaults: '2025-05-24'` or `capture_pageview: 'history_change'` instead, which automatically handles both `$pageview` and `$pageleave` events.
	`195`	+> Note: This approach of manually capturing pageviews is no longer recommended. We recommend using `defaults: '2025-11-30'` or `capture_pageview: 'history_change'` instead, which automatically handles both `$pageview` and `$pageleave` events.
`196`	`196`	`>`
`197`	`197`	> If you're still capturing pageviews manually, you should also capture `$pageleave` events to track important engagement metrics like time on page (`$prev_pageview_duration`) and scroll depth (`$prev_pageview_max_scroll_percentage`). To do this, set up a listener on window unload (similar to [how PostHog does it](https://github.com/PostHog/posthog-js/blob/main/packages/browser/src/posthog-core.ts#L644-L646)):
`198`	`198`	`>`