PostHogConfig

PREVIEW - MAY CHANGE WITHOUT WARNING - DO NOT USE IN PRODUCTION 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)

PREVIEW - MAY CHANGE WITHOUT WARNING - DO NOT USE IN PRODUCTION Whether to use the new /flags/ endpoint

PREVIEW - MAY CHANGE WITHOUT WARNING - DO NOT USE IN PRODUCTION Enables the new RemoteConfig approach to loading config instead of /flags?v=2&config=true

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

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

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

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

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

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

URL of your PostHog instance. 'https://us.i.posthog.com'

The transport method to use for API requests. 'fetch'

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

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

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.

Determines whether to capture dead clicks.

Determines whether to capture exceptions.

Determines whether to capture heatmaps.

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'. 'if_capture_pageview'

Determines whether PostHog should capture pageview events automatically. Can be: - true: Capture regular pageviews (default) - false: Don't capture any pageviews - 'history_change': Only capture pageviews on history API changes (pushState, replaceState, popstate) true

Determines whether to capture performance metrics. These include Network Timing and Web Vitals. 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 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. null

Determines the number of days to store cookies for. 365

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

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.

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

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

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= []

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 false

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') 'unset'

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

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

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

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

Determines whether PostHog should disable session recording. false

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

Determines whether PostHog should disable all surveys functionality. false

Determines whether PostHog should disable web experiments. Currently disabled while we're in BETA. It will be toggled to true in a future release. true

Determines whether PostHog should enable recording console logs. When undefined, it falls back to the remote config setting. undefined

Determines the error tracking options.

Sets timeout for fetching feature flags 3000

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

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.

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

A function to be called once the PostHog scripts have loaded successfully.

Prevent autocapture from capturing any attribute names on elements. false

Prevent autocapture from capturing textContent on elements. false

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

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. 'posthog'

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

Determines if users should be opted in to site apps. false

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

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

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

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

The name for the super properties persistent store ''

Determines how PostHog stores information about the user. See persistence for details. 'localStorage+cookie'

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.group, posthog.setPersonPropertiesForFlags or posthog.setGroupPropertiesForFlags Anonymous users won't get person profiles. 'identified_only'

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.

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

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

Determines whether PostHog should capture rage clicks. true

Client side rate limiting

Determines whether PostHog should batch requests to the PostHog API. true

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

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

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

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

Determines whether PostHog should save referrer information. true

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.

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. window.location.protocol === 'https:'

The segment analytics object.

Determines the session idle timeout in seconds. Any new event that's happened after this timeout will create a new session. 30 * 60 -- 30 minutes

Determines the session recording options.

Sets timeout for fetching surveys 10000

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

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

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