JavaScript Web configuration

When calling posthog.init, there are various configuration options you can set to customize and control the behavior of PostHog.

To configure these options, pass them as an object to the posthog.init call, like we do with api_host, loaded, and autocapture below.

TypeScript

posthog.init('<ph_project_api_key>', {
    api_host: 'https://us.i.posthog.com',
    loaded: function (posthog) {
        posthog.identify('[user unique id]')
    },
    autocapture: false,
    // ... more options
})

You can also use the posthog.set_config method to change the configuration after initialization.

TypeScript

posthog.set_config({
  persistence: 'localStorage+cookie',
})

There are many configuration options, most of which you do not have to ever worry about. For brevity, only the most relevant ones are used here. However you can view all the configuration options in types.ts file of the SDK's source code.

Some of the most relevant options are:

Attribute	Description
`api_host` Type: String Default: `https://us.i.posthog.com`	URL of your PostHog instance.
`ui_host` Type: String Default: undefined	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.
`autocapture` Type: Boolean or AutocaptureConfig Default: `true`	Determines if PostHog should autocapture events. This setting does not affect capturing pageview events (see `capture_pageview`). See below for `AutocaptureConfig`
`before_send` Type: Function Default: `function () {}`	A function that allows you to amend or reject events before they are sent to PostHog. See below for more information
`bootstrap` Type: Object Default: `{}`	An object containing the `distinctID`, `isIdentifiedID`, and `featureFlags` keys, where `distinctID` is a string, and `featureFlags` is an object of key-value pairs
`capture_pageview` Type: Boolean Default: `true`	Determines if PostHog should automatically capture pageview events.
`capture_pageleave` Type: Boolean Default: `true`	Determines if PostHog should automatically capture pageleave events.
`capture_dead_clicks` Type: Boolean Default: `true`	Determines if PostHog should automatically capture dead click events.
`cross_subdomain_cookie` Type: Boolean 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` Type: Array Default: `[]`	A list of user agents to block when sending events.
`disable_persistence` Type: Boolean Default: `false`	Disable persisting user data across pages. This will disable cookies, session storage and local storage.
`disable_surveys` Type: Boolean 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` Type: Boolean Default: `false`	Determines if users should be opted out of session recording.
`enable_recording_console_log` Type: Boolean Default: `false`	Determines if console logs should be recorded as part of the session recording. More information.
`enable_heatmaps` Type: Boolean Default: undefined	Determines if heatmap data should be captured.
`loaded` Type: Function Default: `function () {}`	A function to be called once the PostHog scripts have loaded successfully.
`mask_all_text` Type: Boolean Default: `false`	Prevent PostHog autocapture from capturing any text from your elements.
`mask_all_element_attributes` Type: Boolean Default: `false`	Prevent PostHog autocapture from capturing any attributes from your elements.
`opt_out_capturing_by_default` Type: Boolean Default: `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`.
`opt_out_persistence_by_default` Type: Boolean Default: `false`	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`.
`persistence` Type: Enum: `localStorage`, `sessionStorage`, `cookie`, `memory`, or `localStorage+cookie` Default: `localStorage+cookie`	Determines how PostHog stores information about the user. See persistence for details.
`property_denylist` Type: Array Default: `[]`	A list of properties that should never be sent with `capture` calls.
`person_profiles` Type: Enum: `always`, `identified_only` Default: `identified_only`	Set whether events should capture identified events and process person profiles
`rate_limiting` Type: Object 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` Type: Object Default: See here.	Configuration options for recordings. More details found here
`session_idle_timeout_seconds` Type: Integer Default: `1800`	The maximum amount of time a session can be inactive before it is split into a new session.
`xhr_headers` Type: Object Default: `{}`	Any additional headers you wish to pass with the XHR requests to the PostHog API.

Configuring autocapture

The autocapture config takes an object providing full control of autocapture's behavior.

Attribute	Description
`url_allowlist` Type: Array of Strings or Regexp Default: `undefined`	List of URLs to enable autocapture on, can be string or regex matches e.g. `['https://example.com', 'test.com/.*']`. An empty list means no URLs are allowed for capture, `undefined` means all URLs are.
`dom_event_allowlist` Type: Array of Strings Default: `undefined`	An array of DOM events, like click, change, submit, to enable autocapture on. An empty array means no events are enable for capture, `undefined` means all are.
`element_allowlist` Type: Array of Strings Default: `undefined`	An array of DOM elements, like a, button, form, input, select, textarea, or label to allow autocapture on. An empty array means no elements are enabled for capture, `undefined` means all elements are enabled.
`css_selector_allowlist` Type: Array of Strings Default: `undefined`	An array of CSS selectors to enable autocapture on. An empty array means no CSS selectors are allowed for capture, `undefined` means all CSS selectors are.
`element_attribute_ignorelist` Type: Array of Strings Default: `undefined`	An array of element attributes that autocapture will not capture. Both an empty array and `undefined` mean any of the attributes from the element are captured.
`capture_copied_text` Type: Boolean Default: `false`	When set to true, autocapture will capture the text of any element that is cut or copied.

Advanced configuration

These are features for advanced users and may lead to unintended side effects if not reviewed carefully.

Attribute	Description
`advanced_disable_decide` Type: Boolean Default: `false`	Will completely disable the `/decide` endpoint request (and features that rely on it). More details below.
`advanced_disable_feature_flags` Type: Boolean Default: `false`	Will keep `/decide` running, but without any feature flag requests. Important: do not use this argument if using surveys, as display conditions rely on feature flags internally.
`advanced_disable_feature_flags_on_first_load` Type: Boolean Default: `false`	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.
`feature_flag_request_timeout_ms` Type: Integer Default: `3000`	Sets timeout for fetching feature flags
`secure_cookie` Type: Boolean Default: `false`	If this is `true`, PostHog cookies will be marked as secure, meaning they will only be transmitted over HTTPS.
`custom_campaign_params` Type: Array Default: `[]`	List of query params to be automatically captured (see UTM Segmentation )
`fetch_options.cache` Type: string Default: `undefined`	`fetch` call cache behavior (see MDN Docs to understand available options). It's important when using NextJS, see companion documentation. This is a tricky option, avoid using it unless you are aware of the changes this could cause - such as cached feature flag values, etc.
`fetch_options.next_options` Type: Object Default: `undefined`	Arguments to be passed to the `next` key when calling `fetch` under NextJS. See companion documentation.

Disable `/decide` endpoint

Note: This feature was introduced in posthog-js 1.10.0. Previously, disabling autocapture would inherently disable the /decide endpoint altogether. This meant that disabling autocapture would inadvertently turn off session recording, feature flags, compression, and the toolbar too.

One of the first things the PostHog does after initializing 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 and is required to run most features of the library (detailed below).

If you're not using any of these 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.

The /decide endpoint can be disabled by setting advanced_disable_decide to true.

Resources dependent on `/decide`

Warning: These are features/resources that are fully disabled when the /decide endpoint is disabled.

Autocapture. The /decide endpoint contains information on whether autocapture should be enabled or not (apart from local configuration).
Session recording. The endpoint contains information on where to send relevant session recording events.
Compression. The endpoint contains information on what compression methods are supported on the backend (e.g. LZ64, gzip) for event payloads.
Feature flags. The endpoint contains the feature flags enabled for the current person.
Surveys. The endpoint contains information on whether surveys should be enabled or not.
Toolbar. The endpoint contains authentication information and other toolbar capabilities information required to run it.

Any custom event captures (posthog.capture), $identify, $set, $set_once and basically any other calls not detailed above will work as expected when /decide is disabled.

Configuring autocapture

Advanced configuration

Disable `/decide` endpoint

Resources dependent on `/decide`

Questions? Ask Max AI.

Community questions

Was this page useful?

Managing persistence and cookies

Ian Vanagas

JavaScript Web configuration

Configuring autocapture

Advanced configuration

Disable /decide endpoint

Resources dependent on /decide

Questions? Ask Max AI.

Community questions

Was this page useful?

Managing persistence and cookies

Disable `/decide` endpoint

Resources dependent on `/decide`