JavaScript Web

Last updated:

|Edit this page
Which features are available in this library?
  • Event capture
  • Autocapture
  • User identification
  • Session recording
  • Feature flags
  • Group analytics

Note: This doc refers to our posthog-js library for use on the browser. For server-side JavaScript, see our Node SDK.


Option 1: Add the JavaScript snippet to your HTML Recommended

This is the simplest way to get PostHog up and running. It only takes a few minutes.

Copy the snippet below and replace <ph_project_api_key> and <ph_client_api_host> with your project's values, then add it within the <head> tags at the base of your product - ideally just before the closing </head> tag. This ensures PostHog loads on any page users visit.

You can find the snippet pre-filled with this data in your project settings.

!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
posthog.init('<ph_project_api_key>', {api_host:})

Once the snippet is added, PostHog automatically captures $pageview and other events like button clicks. You can then enable other products, such as session replays, within your project settings.

Option 2: Install via package manager

yarn add posthog-js

And then include it in your files:

import posthog from 'posthog-js'
posthog.init('<ph_project_api_key>', { api_host: })

If you don't want to send test data while you're developing, you can do the following:

if (!'') && !'localhost')) {
posthog.init('<ph_project_api_key>', { api_host: })

If you're using React or Next.js, checkout our React SDK or Next.js integration.

Track across marketing website & app

We recommend putting PostHog both on your homepage and your application if applicable. That means you'll be able to follow a user from the moment they come onto your website, all the way through signup and actually using your product.

PostHog automatically sets a cross-domain cookie, so if your website is and your app is on users will be followed when they go from one to the other.

Permitted domains

You can also configure "permitted domains" in your project settings. These are domains where you'll be able to record user sessions and use the PostHog toolbar.

Capturing events

You can send custom events using capture:


Tip: We recommend using a '[object][verb]' format for your event names, where '[object]' is the entity that the behavior relates to, and '[verb]' is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can also include additional information in the event by setting the properties value:

posthog.capture('user_signed_up', {
login_type: "email",
is_free_trial: true

Page views and autocapture

By default, PostHog automatically captures the following frontend events:

  • Pageviews, including the URL.
  • Autocaptured events, such as any click, change of input, or submission associated with a, button, form, input, select, textarea, and label tags.

If you prefer to disable these, set the appropriate values in your configuration options.

Single-page apps and pageviews

PostHog automatically sends pageview events whenever it gets loaded. If you have a single-page app, that means it only sends a pageview once (when your app loads).

To make sure any navigating a user does within your app gets captured, you can make a pageview call manually.


This automatically sends the current URL along with other relevant properties.

Setting user properties

To set user properties, include them when capturing an event:

$set: { name: 'Max Hedgehog' },
$set_once: { initial_url: '/blog' },

Typically user properties are set when an event occurs like user updated email but there may be occasions where you want to set user properties as its own event.

{ name: "Max Hedgehog" }, // Thes properties are like the `$set` from above
{ initial_url: "/blog" } // Thes properties are like the `$set_once` from above

This creates a special $set event that is sent to PostHog.

For more details on the difference between $set and $set_once, see our user properties docs.

Identifying users

We strongly recommend reading our docs on identifying users to better understand how to correctly use this method.

Using identify, you can associate events with specific users. This enables you to gain full insights as to how they're using your product across different sessions, devices, and platforms.

'distinct_id', // Required. Replace 'distinct_id' with your user's unique identifier
{ email: '', name: 'Max Hedgehog' }, // $set, optional
{ first_visited_url: '/blog' } // $set_once, optional


Sometimes, you may want to assign multiple distinct IDs to a single user. This is helpful in scenarios where your primary distinct ID may be inaccessible. For example, if a distinct ID which is typically used on the frontend is not available in certain parts of your backend code. In this case, you can use alias to assign another distinct ID to the same user.

We strongly recommend reading our docs on alias to best understand how to correctly use this method.

Reset after logout

If a user logs out, you should call reset to unlink any future events made on that device with that user.

This is important if your users are sharing a computer, as otherwise all of those users are grouped together into a single user due to shared cookies between sessions. We strongly recommend you call reset on logout even if you don't expect users to share a computer.

You can do that like so:


If you also want to reset device_id, you can pass true as a parameter:


Super Properties

Super Properties are properties associated with events that are set once and then sent with every capture call, be it a $pageview, an autocaptured button click, or anything else.

They are set using posthog.register, which takes a properties object as a parameter, and they persist across sessions.

For example, take a look at the following call:

'icecream pref': 'vanilla',
team_id: 22,

The call above ensures that every event sent by the user will include "icecream pref": "vanilla" and "team_id": 22. This way, if you filtered events by property using icecream_pref = vanilla, it would display all events captured on that user after the posthog.register call, since they all include the specified Super Property.

However, please note that this does not store properties against the User, only against their events. To store properties against the User object, you should use posthog.setPersonProperties. More information on this can be found on the Sending User Information section.

Furthermore, if you register the same property multiple times, the next event will use the new value of that property. If you want to register a property only once (e.g. for ad campaign properties) you can use register_once, like so:

'campaign source': 'twitter',

Using register_once will ensure that if a property is already set, it will not be set again. For example, if the user already has property "icecream pref": "vanilla", calling posthog.register_once({"icecream pref": "chocolate"}) will not update the property.

Removing stored Super Properties

Setting Super Properties creates a cookie on the client with the respective properties and their values. In order to stop sending a Super Property with events and remove the cookie, you can use posthog.unregister, like so:

posthog.unregister('icecream pref')

This will remove the Super Property and subsequent events will not include it.

Opt users out

PostHog JS offers a function to opt users out based on your cookie settings definition (e.g. preferences set via a cookie banner).

This is also the suggested way to prevent capturing any data from the admin on the page, as well as from team members of your organization. A simple way to do this is to access the page as the admin (or any other user on your team you wish to stop capturing data on), and call posthog.opt_out_capturing(); on the developer console. You can also add this logic in you app and call it directly after an admin/team member logs in.

If you still wish to capture these events but want to create a distinction between users and team in PostHog, you should look into Cohorts.

With PostHog, you can:

Opt a user out:


See if a user has opted out:


Opt a user back in:


Feature Flags

PostHog's feature flags enable you to safely deploy and roll back new features.

Boolean feature flags

if (posthog.isFeatureEnabled('flag-key') ) {
// Do something differently for this user
// Optional: fetch the payload
const matchedFlagPayload = posthog.getFeatureFlagPayload('flag-key')

Multivariate feature flags

if (posthog.getFeatureFlag('flag-key') == 'variant-key') { // replace 'variant-key' with the key of your variant
// Do something differently for this user
// Optional: fetch the payload
const matchedFlagPayload = posthog.getFeatureFlagPayload('flag-key')

Ensuring flags are loaded before usage

Every time a user loads a page, we send a request in the background to fetch the feature flags that apply to that user. We store those flags in your chosen persistence option (local storage by default).

This means that for most pages, the feature flags are available immediately – except for the first time a user visits.

To handle this, you can use the onFeatureFlags callback to wait for the feature flag request to finish:

posthog.onFeatureFlags(function () {
// feature flags are guaranteed to be available at this point
if (posthog.isFeatureEnabled('flag-key')) {
// do something

Reloading feature flags

Feature flag values are cached. If something has changed with your user and you'd like to refetch their flag values, call:


Overriding server properties

Sometimes, you might want to evaluate feature flags using properties that haven't been ingested yet, or were set incorrectly earlier. You can do so by setting properties the flag depends on with these calls:

posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'})

Note: These are set for the entire session. Successive calls are additive: all properties you set are combined together and sent for flag evaluation.

Whenever you set these properties, we also trigger a reload of feature flags to ensure we have the latest values. You can disable this by passing in the optional parameter for reloading:

posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'}, false)

At any point, you can reset these properties by calling resetPersonPropertiesForFlags:


The same holds for group properties:

// set properties for a group
posthog.setGroupPropertiesForFlags({'company': {'property1': 'value', property2: 'value2'}})
// reset properties for a given group:
// reset properties for all groups:

Note: You don't need to add the group names here, since these properties are automatically attached to the current group (set via When you change the group, these properties are reset.

Automatic overrides

Whenever you call posthog.identify with person properties, we automatically add these properties to flag evaluation calls to help determine the correct flag values. The same is true for when you call

Default overridden properties

By default, we always override some properties based on the user IP address.

The list of properties that this overrides:

  1. $geoip_city_name
  2. $geoip_country_name
  3. $geoip_country_code
  4. $geoip_continent_name
  5. $geoip_continent_code
  6. $geoip_postal_code
  7. $geoip_time_zone

This enables any geolocation-based flags to work without manually setting these properties.

Request timeout

You can configure the feature_flag_request_timeout_ms parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog's servers are too slow to respond. By default, this is set at 3 seconds.

posthog.init('<ph_project_api_key>', {
feature_flag_request_timeout_ms: 3000 // Time in milliseconds. Default is 3000 (3 seconds).

Bootstrapping Flags

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

To have your feature flags available immediately, you can initialize PostHog with precomputed values until PostHog has had a chance to fetch them. This is called bootstrapping.

For details on how to implement bootstrapping, see our bootstrapping guide.

Enriched analytics

You can send enriched analytics data for feature flags, which helps uncover replays where people interact with a flag, target people who've interacted with a feature, or build cohorts of people who've viewed a feature.

To enable this, you can either use our <PosthogFeature> React component (which implements this for you), or implement it on your own if you're not using react.

To implement it on your own, there are 3 things you need to do:

  1. Whenever a feature is viewed, send the $feature_view event with the property feature_flag set to the name of the flag.
posthog.capture('$feature_view', { feature_flag: flag })
  1. Whenever someone interacts with a feature, send the $feature_interaction event with the property feature_flag set to the name of the flag.
  2. At the same time, set the person property $feature_interaction/<flag-key> to true. Here's a code example.
posthog.capture('$feature_interaction', { feature_flag: flag, $set: { [`$feature_interaction/${flag}`]: true } })

Here's a code example for the entire React component.

Experiments (A/B tests)

Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code:

// Ensure flags are loaded before usage.
// You'll only need to call this on the code the first time a user visits.
// See this doc for more details:
posthog.onFeatureFlags(function() {
// feature flags should be available at this point
if (posthog.getFeatureFlag('experiment-feature-flag-key') == 'variant-name') {
// do something
// Otherwise, you can just do:
if (posthog.getFeatureFlag('experiment-feature-flag-key') == 'variant-name') {
// do something
// You can also test your code by overriding the feature flag:
// e.g., posthog.featureFlags.override({'experiment-feature-flag-key': 'test'})

It's also possible to run experiments without using feature flags.

Early access feature management

Early access features give you the option to release feature flags that can be controlled by your users. More information on this can be found here.

posthog.getEarlyAccessFeatures((previewItemData) => {
// do something with early access feature
posthog.updateEarlyAccessFeatureEnrollment(flagKey, 'true')

Group analytics

Group analytics allows you to associate the events for that person's session with a group (e.g. teams, organizations, etc.). Read the Group Analytics guide for more information.

Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more here.

  • Associate the events for this session with a group
Web'company', 'company_id_in_your_db')
posthog.capture('upgraded_plan') // this event is associated with company ID `company_id_in_your_db`
  • Associate the events for this session with a group AND update the properties of that group
Web'company', 'company_id_in_your_db', {
name: 'Awesome Inc.',
employees: 11,

The name is a special property which is used in the PostHog UI for the name of the Group. If you don't specify a name property, the group ID will be used instead.

Handling logging out

When the user logs out it's important to call posthog.reset() to avoid new events being registered under the previously active group.

Integrating groups with feature flags

If you have updated tracking, you can use group-based feature flags as normal.

if (posthog.isFeatureEnabled('new-groups-feature')) {
// do something

To check flag status for a different group, first switch the active group by calling


Surveys launched with popover presentation are automatically shown to users matching the targeting you set up.

To disable loading surveys in a specific client, you can set the disable_surveys config option.

Surveys using the API presentation enable you to implement your own survey UI and use PostHog to handle display logic, capturing results, and analytics.

To implement API surveys, start by fetching active surveys for a user using either of the methods below:

// Fetch enabled surveys for the current user
posthog.getActiveMatchingSurveys(callback, forceReload)
// Fetch all surveys
posthog.getSurveys(callback, forceReload)

The response returns an array of survey objects and is cached by default. To force a reload, pass true as the forceReload argument.

The survey objects look like this:

"id": "your_survey_id",
"name": "Your survey name",
"description": "Metadata describing your survey",
"type": "api", // either "api", "popover", or "widget"
"linked_flag_key": null, // linked feature flag key, if any.
"targeting_flag_key": "your_survey_targeting_flag_key",
"questions": [
"type": "single_choice",
"choices": [
"question": "Are you enjoying PostHog?"
"conditions": null,
"start_date": "2023-09-19T13:10:49.505000Z",
"end_date": null

Capturing survey events

To display survey results in PostHog, you need to capture 3 types of events:

// 1. When a user is shown a survey
posthog.capture("survey shown", {
$survey_id: // required
// 2. When a user has dismissed a survey
posthog.capture("survey dismissed", {
$survey_id: // required
// 3. When a user has responded to a survey
posthog.capture("survey sent", {
$survey_id:, // required
$survey_response: survey_response // required. `survey_response` must be a text value.
// Convert numbers to text e.g. 8 should be converted "8".
// For multiple choice select surveys, `survey_response` must be an array of values with the selected choices.
// e.g., $survey_response: ["response_1", "response_2"]

Session replay

To set up session replay in your project, all you need to do is install the JavaScript web library and enable "Record user sessions" in your project settings.

For fine-tuning control of which sessions you record, you can set the disable_session_recording config option and use the following methods:

// Turns session recording on
// Turns session recording off
// Check if session recording is currently running

To get the playback URL of the current session replay, you can use the following method:

{ withTimestamp: true, timestampLookBack: 30 }

It has two optional parameters:

  • withTimestamp (default: false): When set to true, the URL includes a timestamp that takes you to the session at the time of the event.
  • timestampLookBack (default: 10): The number of seconds back the timestamp links to.


For PostHog to work optimally, we store small amount of information about the user on the user's browser. This ensures we identify users properly if they navigates away from your site and come back later. We store the following information in the user's browser:

  • User's ID
  • Session ID & Device ID
  • Active & enabled feature flags
  • Any super properties you have defined.
  • Some PostHog configuration options (e.g. whether session recording is enabled)

By default, we store all this information in a cookie, which means PostHog can identify your users across subdomains. By default, this cookie is set to expire after 365 days and is named with your Project API key e.g. ph_<project_api_key>_posthog.

If you want to change how PostHog stores this information, you can do so with the persistence configuration option:

  • persistence: "localStorage+cookie" (default): Limited things are stored in the cookie such as the distinctID and the sessionID, and everything else in the browser's localStorage.

  • persistence: "cookie" : Stores all data in a cookie.

  • persistence: "localStorage": Stores everything in localStorage.

  • persistence: "sessionStorage": Stores everything in sessionStorage.

  • persistence: "memory": Stores everything in page memory, which means data is only persisted for the duration of the page view.

To change persistence values without reinitializing PostHog, you can use the posthog.set_config() method. This enables you to switch from memory to cookies to better comply with privacy regulations.

const handleCookieConsent = (consent) => {
posthog.set_config({ persistence: consent === 'yes' ? 'localStorage+cookie' : 'memory' });
localStorage.setItem('cookie_consent', consent);

Persistence caveats

  • Be aware that localStorage and sessionStorage can't be used across subdomains. If you have multiple sites on the same domain, you may want to consider a cookie option or make sure to set all super properties across each subdomain.

  • Due to the size limitation of cookies you may run into 431 Request Header Fields Too Large errors (e.g. if you have a lot of feature flags). In that case, use localStorage+cookie.

  • If you don't want PostHog to store anything on the user's browser (e.g. if you want to rely on your own identification mechanism only or want completely anonymous users), you can set disable_persistence: true in PostHog's config. If you do this, remember to call posthog.identify every time your app loads. If you don't, every page refresh is treated as a new and different user.


When calling posthog.init, there are various configuration options you can set in addition to loaded and api_host.

To configure these options, pass them as an object to the posthog.init call, like so:

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

There are multiple different 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 posthog-core.js.

Some of the most relevant options are:


Type: String
URL of your PostHog instance.

Type: String
Default: undefined
If using a reverse proxy for api_host then this should be the actual PostHog app URL (e.g.

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)

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

Type: Boolean
Default: true
Determines if PostHog should automatically capture pageview events.

Type: Boolean
Default: true
Determines if PostHog should automatically capture pageleave events.

Type: Boolean
Default: true
Determines if cookie should be set on the top level domain ( If PostHog-js is loaded on a subdomain (, and cross_subdomain_cookie is set to false, it'll set the cookie on the subdomain only (

Type: Boolean
Default: false
Disable persisting user data across pages. This will disable cookies, session storage and local storage.

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

Type: Boolean
Default: false
Determines if users should be opted out of session recording.

Type: Boolean
Default: false
Determines if console logs should be recorded as part of the session recording. More information.

Type: Function
Default: function () {}
A function to be called once the PostHog scripts have loaded successfully.

Type: Boolean
Default: false
Prevent PostHog autocapture from capturing any text from your elements.

Type: Boolean
Default: false
Prevent PostHog autocapture from capturing any attributes from your elements.

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.

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.

Type: localStorage or sessionStorage or cookie or memory or localStorage+cookie
Default: cookie
Determines how PostHog stores information about the user. See persistence for details.

Type: Array
Default: []
A list of properties that should never be sent with capture calls.

Type: Function
Default: null
A function that allows you to sanitize or modify the properties that get sent. Example: sanitize_properties: function(properties, event) { if(properties['$ip']) { properties['$ip'] = null } return properties }

Type: Object
Default: See here.
Configuration options for recordings. More details found here

Type: Object
Default: {}
Any additional headers you wish to pass with the XHR requests to the PostHog API.

Advanced configuration

In this section we describe some additional details on advanced configuration available.


Type: Boolean
Default: false
Will completely disable the /decide endpoint request (and features that rely on it). More details below.

Type: Boolean
Default: false
Will keep /decide running, but without any feature flag requests

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.

Type: Integer
Default: 3000
Sets timeout for fetching feature flags

Type: Boolean
Default: false
If this is true, PostHog cookies will be marked as secure, meaning they will only be transmitted over HTTPS.

Type: Array
Default: []
List of query params to be automatically captured (see UTM Segmentation )
These are features for advanced users and may lead to unintended side effects if not reviewed carefully. If you are unsure about something, just reach out.

Disable /decide endpoint

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 inadvertenly turn off session recording, feature flags, compression and the toolbar too.

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

The /decide endpoint can be disabled by setting advanced_disable_decide = true in PostHog config.

Resources dependent on /decide

These are features/resources that will be 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 capturing (posthog.capture), $identify, $set, $set_once and basically any other calls not detailed above will work as expected when /decide is disabled.


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


Type: Array of Strings or Regexp
Default: undefined
List of URLs to enable autocapture on, can be string or regex matches e.g. ['', '*']. An empty list means no URLs are allowed for capture, undefined means all URLs are.

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.

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.

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.

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.


In your dev console you can run posthog.debug(). This will enable debugging, easily allowing you to see all data that is being sent to PostHog.


For instructions on how to run posthog-js locally and setup your development environment, please checkout the README on the posthog-js repository.


Was this page useful?

Next article


It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your mobile app. Installation Capturing events Identify We highly recommend reading our section on Identifying users to better understand how to correctly use this method. Setting user properties via an event To set properties on your users via an event, you can leverage the event properties userProperties and userPropertiesSetOnce…

Read next article