--- title: JavaScript Web configuration slug: /docs/libraries/js/config --- # 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. ```ts posthog.init('', { api_host: '', defaults: '', 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. ```ts 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](/docs/references/posthog-js/types/PostHogConfig.md). 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](/docs/advanced/proxy.md) 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](/docs/product-analytics/autocapture.md) events. This setting does not affect capturing pageview events (see `capture_pageview`). [See below for `AutocaptureConfig`](#configuring-autocapture) | | `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](/docs/libraries/js/features#amending-or-sampling-events.md) | | `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`](/docs/libraries/js/features#blocking-bad-actors.md)

**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 `''` 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](/docs/session-replay/manual#console-logs-recording.md). | | `enable_heatmaps`

**Type:** Boolean
**Default:** undefined | Determines if heatmap data should be captured. | | `evaluation_environments`

**Type:** Array of Strings
**Default:** `undefined` | Environment tags that constrain which feature flags are evaluated. When set, only flags with matching evaluation tags (or no evaluation tags) will be returned. This helps reduce unnecessary flag evaluations and improves performance. See [evaluation tags documentation](/docs/feature-flags/evaluation-tags.md) 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](/docs/libraries/js/persistence.md) 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.](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.md) | | `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-rageclick) | | ## 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](/docs/data/utm-segmentation.md) ) | | `fetch_options.cache`

**Type:** string
**Default:** `undefined` | `fetch` call cache behavior (see [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#cache) to understand available options). It's important when using NextJS, see [companion documentation](https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options). 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](https://nextjs.org/docs/app/api-reference/functions/fetch#optionsnextrevalidate). | | `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](/docs/api/flags.md) 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.