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, defaults, loaded, and autocapture below.

TypeScript

posthog.init('<ph_project_api_key>', {
    api_host: 'https://us.i.posthog.com',
    defaults: '2025-05-24',
    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 options in the PostHogConfig specification.

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 or String Default: `true`	Determines if PostHog should automatically capture pageview events. The default is to capture using page load events. If the special string `history_change` is provided, PostHog will capture pageviews based on path changes by listening to the browser's history API which is useful for single page apps. `history_change` is the default if you choose to set `defaults: '2025-05-24'` or later.
`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.
`defaults` Type: String 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.
`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.
`evaluation_environments` Type: Array of Strings Default: `undefined`	Environment environments that constrain which feature flags are evaluated. When set, only flags with matching evaluation environments (or no evaluation environments) will be returned. This helps reduce unnecessary flag evaluations and improves performance. See evaluation environments documentation for more details.
`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.
`rageclick` Type: Boolean or RageclickConfig Default: `true`	Determines if PostHog should automatically capture rage click events when users rapidly click on elements that don't respond. See below for `RageclickConfig`

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.

Configuring rageclick

We provide a convenient .ph-no-rageclick class that automatically excludes elements from rage click tracking.

But if you need more control, we also provide a rageclick config that takes an object providing control over rage click event detection.

Attribute	Description
`css_selector_ignorelist` Type: Array of Strings 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.

Advanced configuration

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

Attribute	Description
`advanced_disable_flags` Type: Boolean Default: `false`	Will completely disable the `/flags` endpoint request (and features that rely on it). More details below.
`advanced_disable_decide` Type: Boolean Default: `false`	Legacy, prefer `advanced_disable_flags`. This configuration option behaves like `advanced_disable_flags` but will be deprecated in the future.
`advanced_disable_feature_flags` Type: Boolean Default: `false`	Will keep `/flags` 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.
`advanced_only_evaluate_survey_feature_flags` Type: Boolean Default: `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.
`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.
`on_request_error` Type: Function Default: `logger.error('Bad HTTP status: ' + res.statusCode + ' ' + res.text)`	Called whenever a PostHog request fails with an HTTP status code of 400 or higher. The callback function receives a `RequestResponse` object with the `statusCode`, `text`, and `json` (if available).

Disable `/flags` endpoint

Note: This feature was introduced in posthog-js 1.10.0. Previously, disabling autocapture would inherently disable the /flags 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 /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 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 /flags endpoint can be disabled by setting advanced_disable_flags to true.

Resources dependent on `/flags`

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

Autocapture. The /flags 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 /flags is disabled.

JavaScript Web configuration

Contents

Configuring autocapture

Configuring rageclick

Advanced configuration

Disable `/flags` endpoint

Resources dependent on `/flags`

Community questions

Was this page useful?

JavaScript Web configuration

Contents

Contents

Configuring autocapture

Configuring rageclick

Advanced configuration

Disable /flags endpoint

Resources dependent on /flags

Community questions

Was this page useful?

Disable `/flags` endpoint

Resources dependent on `/flags`