PostHogConfig

The name this instance will be identified by. You don't need to set this most of the time, but can be useful if you have several Posthog instances running at the same time.

URL of your PostHog instance.

URL to use for feature flag requests specifically. If not set, feature flag requests will use the URL derived from api_host. This is useful when you want to route feature flag requests to a different endpoint than other analytic APIs.

If using a reverse proxy for api_host then this should be the actual PostHog app URL (e.g. https://us.posthog.com). This ensures that links to PostHog point to the correct host.

The transport method to use for API requests.

The token for your PostHog project. It should NOT be provided manually in the config, but rather passed as the first parameter to posthog.init().

Determines whether PostHog should autocapture events. This setting does not affect capturing pageview events (see capture_pageview).

by default autocapture is ignored on elements that match a ph-no-capture css class on the element or a parent

Determines whether PostHog should capture rage clicks.

By default, rage clicks are ignored on elements that match a ph-no-capture or ph-no-rageclick CSS class on the element or a parent. When defaults is '2025-11-30' or later, the default is { content_ignorelist: true }. When defaults is '2026-05-30' or later, the default also excludes stepper controls (+, -, −, –) and text-selection surfaces.

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).

NOTE: It will be set to false if we detect that the domain is a subdomain of a platform that is excluded from cross-subdomain cookie setting. The current list of excluded platforms is herokuapp.com, vercel.app, and netlify.app.

Determines how PostHog stores information about the user. See persistence for details.

The name for the super properties persistent store

Deprecated: - Use 'persistence_name' instead

List of custom property names that should be stored in cookies (in addition to the default ones) when using 'localStorage+cookie' persistence mode. This allows these properties to be shared across subdomains when cross_subdomain_cookie is enabled.

Determines whether PostHog should strip URL fragments (#...) from automatically captured URL fields. Disabled by default for backwards compatibility, and enabled automatically when config.defaults is '2026-06-25' or later. Set to true to strip hashes from:

• $current_url on automatically captured browser events, including $pageview
• $initial_current_url
• $session_entry_url
• $elements[*].attr__href and $external_click_url for autocapture and dead-click autocapture
• Next.js Pages Router $pageview $current_url
• web vitals $current_url
• logs url.full
• conversations current_url and request_url
• session replay rrweb meta/custom-event href URLs
• heatmap data URLs

If your SPA relies on hash-based routes for analytics, enabling this is a breaking behavior change. If you want to capture hashes selectively, leave this disabled and use before_send to remove sensitive hash values before events are sent.

Determines whether PostHog should save referrer information.

Determines whether PostHog should save marketing parameters. These are utm_* paramaters and friends.

Deprecated: - Use save_campaign_params instead

Used to extend the list of campaign parameters that are saved by default.

Used to extend the list of user agents that are blocked by default.

Determines whether PostHog should be in debug mode. You can enable this to get more detailed logging.

You can also enable this on your website by appending ?__posthog_debug=true at the end of your URL You can also call posthog.debug() in your code to enable debug mode

Deprecated: Use debug instead

Determines whether PostHog should capture pageview events automatically. Can be:

• true: Capture regular pageviews (default)
• false: Don't capture any pageviews
• 'history_change': Capture pageviews on the initial page load and on history API changes (pushState, replaceState, popstate)

Determines whether PostHog should capture pageleave events. If set to true, it will capture pageleave events for all pages. If set to 'if_capture_pageview', it will only capture pageleave events if capture_pageview is also set to true or 'history_change'.

Determines the number of days to store cookies for.

Determines whether PostHog should upgrade old cookies. If set to true, the library will check for a cookie from our old js library and import super properties from it, then the old cookie is deleted. This option only works in the initialization, so make sure you set it when you create the library.

Determines whether PostHog should disable session recording.

Determines whether PostHog should disable persistence. If set to true, the library will not save any data to the browser. It will also delete any data previously saved to the browser.

Deprecated: - use disable_persistence instead

Coalesce rapid Persistence.save() calls into a single write.

Set to a positive number (milliseconds) to debounce writes to localStorage / cookie by that window. The in-memory props object is always updated synchronously so within-tab reads see the latest values immediately. Cross-tab storage events (which carry the full persistence value as a payload) are reduced proportionally to the debounce window.

Pending writes are flushed on beforeunload and pagehide so no state is lost on tab close. The cross-tab visibility delay is bounded by the configured window.

Defaults to 0 (no debouncing, write synchronously) for backwards compatibility. On pages that capture many events per second, 250 is a reasonable starting point to reduce localStorage write pressure and cross-tab IPC traffic. The 2026-05-30 config default opts into 250 automatically.

Store the feature-flag config cluster and survey config in their own localStorage entries (<name>__flags, <name>__surveys) instead of the single main persistence blob. These payloads are large and change rarely, so keeping them out of the main blob stops them riding on every high-frequency main-blob write and broadcasting cross-tab storage events.

Only applies when persistence resolves to localStorage / localStorage+cookie (the split is pointless for memory / sessionStorage and impossible for cookie). On load the old main-blob location is read once and migrated forward, so upgrades never miss a cached flag. The 2026-05-30 config default opts in.

Detect the Google Search App (GSA) as its own $browser value instead of the underlying webview it embeds — Mobile Safari on iOS, Chrome on Android. Detection keys off the GSA/ marker present in the UA on every platform.

Off by default for backwards-compatibility: enabling it reattributes existing GSA traffic away from Mobile Safari / Chrome, which would otherwise look like those browsers suddenly losing share. The 2026-05-30 config default opts in.

Determines whether PostHog should disable all surveys functionality.

Determines whether PostHog should disable automatic display of surveys. If this is true, popup or widget surveys will not be shown when display conditions are met.

Determines whether PostHog should disable all product tours functionality.

Survey-specific configuration options.

Logs-specific configuration options.

Metrics-specific configuration options for the posthog.metrics API.

Determines whether PostHog should disable all conversations functionality.

Verified distinct_id for HMAC-based identity verification. When both identity_distinct_id and identity_hash are provided, products like conversations use server-verified identity instead of anonymous session identifiers.

Can be set at init time or later via posthog.setIdentity().

HMAC-SHA256 of identity_distinct_id using the project's API secret. Must be provided together with identity_distinct_id.

Determines whether PostHog should disable web experiments.

Currently disabled while we're in BETA. It will be toggled to true in a future release.

Determines whether PostHog should disable any external dependency loading. This will prevent PostHog from requesting any external scripts such as those needed for Session Replay, Surveys or Site Apps.

Determines whether PostHog should load external dependency scripts from semver-qualified asset paths such as /static/1.370.0/recorder.js instead of the legacy /static/recorder.js?v=1.370.0 form.

Optional host override for static assets loaded by PostHog, such as recorder.js, surveys.js, or toolbar.js. Only applies to /static/* asset paths; dynamic assets like remote config continue to use the regular asset host derived from api_host.

A function to be called when a script is being loaded. This can be used to modify the script before it is loaded. This is useful for adding a nonce to the script, for example.

A function to be called when a stylesheet is being loaded. This can be used to modify the stylesheet before it is loaded. This is useful for adding a nonce to the stylesheet, for example.

Where to inject external dependency scripts (recorder, surveys, etc.) in the DOM.

• 'body': Injects scripts into document.body (legacy behavior)
• 'head': Injects scripts into document.head (avoids SSR hydration errors)

Determines whether PostHog should enable recording console logs.

This is related to the Session Recording feature. For more session recording settings, see the session_recording and capture_performance configuration option. When undefined, it falls back to the remote config setting.

Determines whether PostHog should use secure cookies. If this is true, PostHog cookies will be marked as secure, meaning they will only be transmitted over HTTPS.

Determines if users should be opted out of PostHog tracking by default, requiring additional logic to opt them into capturing by calling posthog.opt_in_capturing().

Determines where we'll save the information about whether users are opted out of capturing.

Determines if users should be opted out of browser data storage by this PostHog instance by default, requiring additional logic to opt them into capturing by calling posthog.opt_in_capturing().

Determines if users should be opted out of user agent filtering such as googlebot or other bots. If this is set to true, PostHog will set $browser_type to either bot or browser for all events, but will process all events as if they were from a browser.

Deprecated: Use consent_persistence_name instead. This will be removed in a future major version.

Determines the key for the cookie / local storage used to store the information about whether users are opted in/out of capturing. When null, we used a key based on your token.

Determines if users should be opted in to site apps.

Determines whether PostHog should respect the Do Not Track header when computing consent in ConsentManager.

A list of properties that should never be sent with capture calls.

Deprecated: - use property_denylist instead

A list of headers that should be sent with requests to the PostHog API.

Deprecated: - use request_headers instead

A function that is called when a request to the PostHog API fails.

Deprecated: - use on_request_error instead

Determines whether PostHog should batch requests to the PostHog API.

Determines the maximum length of the properties string that can be sent with capture calls.

Configuration defaults for breaking changes. When set to a specific date, enables new default behaviors that were introduced on that date.

• 'unset': Use legacy default behaviors
• '2025-05-24': Use updated default behaviors (e.g. capture_pageview defaults to 'history_change')
• '2025-11-30': Defaults from '2025-05-24' plus additional changes (e.g. strict minimum duration for replay and rageclick content ignore list defaults to active)
• '2026-01-30': Defaults from '2025-11-30' plus external_scripts_inject_target defaults to 'head' (avoids SSR hydration errors)
• '2026-05-30': Defaults from '2026-01-30' plus persistence_save_debounce_ms defaults to 250, split_storage and detect_google_search_app default to true, and rageclick defaults also exclude stepper controls and text-selection surfaces
• '2026-06-25': Defaults from '2026-05-30' plus session_recording.streamNetworkBody defaults to true (streams network bodies to enforce the payload size limit)

Determines the session recording options.

For more session recording settings, see the enable_recording_console_log and capture_performance configuration option. When defaults is '2025-11-30' or later, strictMinimumDuration defaults to true.

Determines the error tracking options.

Determines the session idle timeout in seconds.

If no events are captured for this many seconds, the next event starts a new session with a new $session_id (and $window_id). The SDK may also proactively reset the stored session after the timeout while the page is idle, so the next event creates a new session.

Session recording has a separate idle threshold: session_recording.session_idle_threshold_ms. That setting only controls when the user is considered idle, it does not rotate $session_id.

Must be between 60 seconds and 10 hours. Values outside this range are clamped.

Prevent autocapture from capturing any attribute names on elements.

Prevent autocapture from capturing textContent on elements.

Mask personal data properties from the current URL. This will mask personal data properties such as advertising IDs (gclid, fbclid, etc.), and you can also add custom properties to mask with custom_personal_data_properties.

Custom list of personal data properties to mask.

E.g. if you added email to this list, then any email property in the URL will be masked. https://www.example.com/login?email=john.doe%40example.com => https://www.example.com/login?email=<MASKED>

One of the very first things the PostHog library does when init() is called is make a request to the /flags endpoint on PostHog's backend. This endpoint contains information on how to run the PostHog library so events are properly received in the backend, and it also contains feature flag evaluation information for the current user.

This endpoint is required to run most features of this library. However, if you're not using any of the described features, you may wish to turn off the call completely to avoid an extra request and reduce resource usage on both the client and the server.

WARNING: Disabling this will also prevent remote configuration from loading, which could mean features like web vitals, surveys, and other features configured in PostHog settings are disabled unless explicitly enabled via client-side config. When setting this to true, make sure to explicitly configure any features you want to use (e.g., capture_performance, autocapture, etc.) in your SDK's init config.

Deprecated: Use advanced_disable_flags instead. This will be removed in a future major version.

One of the very first things the PostHog library does when init() is called is make a request to the /decide endpoint on PostHog's backend. This endpoint contains information on how to run the PostHog library so events are properly received in the backend.

This endpoint is required to run most features of the library. However, if you're not using any of the described features, you may wish to turn off the call completely to avoid an extra request and reduce resource usage on both the client and the server.

Will keep /flags running, but without evaluating any feature flags. Useful for when you need to load the config data associated with the flags endpoint (e.g. /flags?v=2&config=true) without evaluating any feature flags. Most folks use this to save money on feature flag evaluation (by bootstrapping feature flags on the server side).

Stops from firing feature flag requests on first page load. Only requests feature flags when user identity or properties are updated, or you manually request for flags to be loaded.

Evaluation contexts for feature flags. When set, only feature flags that have at least one matching evaluation tag will be evaluated for this SDK instance. Feature flags with no evaluation tags will always be evaluated.

Examples: ['production', 'web', 'checkout']

List of feature flag keys to remotely evaluate for this SDK instance. When set, only these flags are evaluated by /flags; omitted flags are not remotely evaluated. Dependencies of the requested flags may still be evaluated internally by PostHog. If unset, all eligible flags are evaluated.

Examples: ['checkout-redesign', 'new-onboarding']

Evaluation environments for feature flags. Deprecated: Use evaluation_contexts instead. This property will be removed in a future version.

Determines whether PostHog should disable toolbar metrics. This is our internal instrumentation for our toolbar in your website.

Determines whether PostHog should only evaluate feature flags for surveys. Useful for when you want to use this library to evaluate feature flags for surveys only but you have additional feature flags that you evaluate on the server side.

When this is enabled, surveys will always be initialized, regardless of the /flags response or remote config settings. This is useful if you want to use surveys but disable all other flag-dependent functionality. Used internally for displaying external surveys without making a /flags request.

Sets timeout for fetching feature flags

Sets the maximum age (in milliseconds) for cached feature flag values. When the cache is older than this value:

• getFeatureFlag() will return undefined instead of stale cached values
• $feature/ properties will not be attached to events
• A background refresh will be triggered automatically

This prevents stale feature flag values from being used when the /flags request fails (e.g., due to ad blockers or network issues).

When not set or set to 0, cache expiration is disabled (cached values never expire).

When enabled, $feature_flag_called event deduplication is scoped to the current session.

By default, the SDK deduplicates $feature_flag_called events globally and only re-emits them when identify (with a new distinct ID) or reset is called. This can be problematic for experiments: if a flag is checked before an experiment starts, the event is cached and won't fire again for that user until identify/reset, meaning the experiment never sees the event.

When this option is true, the deduplication cache is keyed on the session ID, so each new session will re-emit $feature_flag_called for every flag that is checked.

Sets timeout for fetching surveys

Controls how often feature flags are automatically refreshed in long-running sessions after remote configuration has loaded.

By default, feature flags are refreshed every 5 minutes (300000ms) to pick up server-side flag changes without requiring a page reload. This is useful for SPAs and long-running tabs.

Tradeoffs:

• Shorter intervals: Feature flag changes propagate faster, but increases network requests and server load.
• Longer intervals: Reduces network traffic (better for mobile/battery), but flag changes take longer to propagate.
• Disabled (0): No background refreshes. Flags only update on page load or manual reloadFeatureFlags() calls. Use this if you control flag updates manually or have infrequent flag changes.

Note: Refreshes are automatically skipped when the browser tab is hidden or no document is available.

Function to get the device ID. This doesn't usually need to be set, but can be useful if you want to use a custom device ID.

This function or array of functions - if provided - are called immediately before sending data to the server. It allows you to edit data before it is sent, or choose not to send it all. if provided as an array the functions are called in the order they are provided any one function returning null means the event will not be sent

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 features match against window.location.href directly, which does not reflect any $current_url you rewrite in before_send. In environments where the browser URL is not meaningful for targeting — e.g. Electron/desktop apps served from a generated host — return the logical URL you want these features to match against. This does not change the $current_url property captured on events (use before_send for that).

Deprecated: - use before_send instead

Deprecated: - use before_send instead

Determines whether to capture performance metrics. These include Network Timing for Session Replay and Web Vitals.

The network_timing option is only used by the Session Replay feature. For more session recording settings, see the session_recording and enable_recording_console_log configuration option.

When undefined, fallback to the remote configuration. If false, neither network timing nor web vitals will work. If an object, that will override the remote configuration.

Determines whether to disable compression when sending events to the server. WARNING: Should only be used for testing. Could negatively impact performance.

An object containing the distinctID, isIdentifiedID, and featureFlags keys, where distinctID is a string, and featureFlags is an object of key-value pairs.

Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This makes them unusable if you want to do something like redirecting a user to a different page based on a feature flag.

You can, therefore, fetch the feature flags in your server and pre-fill them here, allowing PostHog to know the feature flag values immediately.

After the SDK fetches feature flags from PostHog, it will use those flag values instead of bootstrapped ones.

The segment analytics object.

Determines whether to capture heatmaps.

Deprecated: Use capture_heatmaps instead.

Determines whether to capture dead clicks.

by default dead clicks are ignored on elements that match a ph-no-capture or ph-no-deadclick css class on the element or a parent

Determines whether to capture exceptions.

Determines whether to disable scroll properties. These allow you to keep track of how far down someone scrolled in your website.

Let the pageview scroll stats use a custom css selector for the root element, e.g. main It will use window.document.documentElement if not specified.

You can control whether events from PostHog-js have person processing enabled with the person_profiles config setting. There are three options:

• person_profiles: 'always' - we will process persons data for all events
• person_profiles: 'never' - we won't process persons for any event. This means that anonymous users will not be merged once they sign up or login, so you lose the ability to create funnels that track users from anonymous to identified. All events (including $identify) will be sent with $process_person_profile: False.
• person_profiles: 'identified_only' (default) - we will only process persons when you call posthog.identify, posthog.alias, posthog.setPersonProperties, posthog.unsetPersonProperties, posthog.group, posthog.setPersonPropertiesForFlags or posthog.setGroupPropertiesForFlags Anonymous users won't get person profiles.

Deprecated: - use person_profiles instead

Client side rate limiting

Used when sending data via fetch, use with care. This is intentionally meant to be used with NextJS fetch

Incorrect cache usage may cause out-of-date data for feature flags, actions tracking, etc. See https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options

Used to change the behavior of the request queue. This is an advanced feature and should be used with caution.

Used to set-up external integrations with PostHog data - such as session replays, distinct id, etc.

Enables cookieless mode. In this mode, PostHog will not set any cookies, or use session or local storage. User identity is handled by generating a privacy-preserving hash on PostHog's servers.

Web Vitals (capture_performance.web_vitals) are supported: metrics are sent without client session IDs; ingestion assigns $session_id when cookieless mode is enabled for the project.

• 'always' - enable cookieless mode immediately on startup, use this if you do not intend to show a cookie banner
• 'on_reject' - enable cookieless mode only if the user rejects cookies, use this if you want to show a cookie banner. If the user accepts cookies, cookieless mode will not be used, and PostHog will use cookies and local storage as usual.

Note that you MUST enable cookieless mode in your PostHog project's settings, otherwise all your cookieless events will be ignored. We plan to remove this requirement in the future.

A hostname pattern to match test environments. When the current hostname matches, setInternalOrTestUser() is called automatically on startup, enabling person processing and setting $internal_or_test_user: true.

Can be a string (exact match) or RegExp (pattern match). Set to null to explicitly disable (useful when using defaults: '2026-01-30').

Display language override for Product Tours.

Must be a valid BCP 47 language code.

In the future this will be used for Surveys and other products that deliver in-app experiences to end-users.

A list of hostnames for which to inject PostHog tracing headers to all requests (X-POSTHOG-DISTINCT-ID, X-POSTHOG-SESSION-ID, X-POSTHOG-WINDOW-ID). Used to link frontend sessions to backend traces (see https://posthog.com/docs/llm-analytics/link-session-replay).

Deprecated: Use {@link tracing_headers} instead. Kept for backwards compatibility.

Deprecated: Use {@link tracing_headers} instead. Kept for backwards compatibility.

Deprecated: This option is a no-op. The browser SDK already uses the /flags/?v=2 endpoint.

Deprecated: This option is a no-op. Session replay is lazy-loaded by default.

Prevents posthog-js from using the navigator.sendBeacon API to send events. Enabling this option may hurt the reliability of sending $pageleave events.

Deprecated: Use disable_beacon instead.

Deprecated: This option is a no-op. The browser SDK no longer sets XMLHttpRequest.withCredentials.

Deprecated: Use {@link strict_script_versioning} and {@link asset_host} instead. When set to true, this is equivalent to strict_script_versioning: true. When set to a string, this is equivalent to strict_script_versioning: true and asset_host set to that string.

Deprecated: - does nothing was present only for PostHog testing of replay lazy loading

Deprecated: - NOT USED ANYMORE, kept here for backwards compatibility reasons

Deprecated: - NOT USED ANYMORE, kept here for backwards compatibility reasons

Deprecated: - NOT USED ANYMORE, kept here for backwards compatibility reasons

Deprecated: - THIS OPTION HAS NO EFFECT, kept here for backwards compatibility reasons. Use a custom transformation or "Discard IP data" project setting instead:

Disables capturing the $device_model super-property.

When capturing is enabled (the default), PostHog resolves the hardware model once during init via navigator.userAgentData.getHighEntropyValues(['model']) and registers it as the raw OEM code (e.g. Pixel 7). This is Chromium-only and only meaningful on Android — it resolves to undefined on Safari/Firefox and to an empty string on desktop, in which cases nothing is registered.

This opt-out is offered because getHighEntropyValues is still experimental and Chromium-only (not yet a cross-browser standard); set it to true to skip the call entirely.