Web experiments installation

  1. Install PostHog JavaScript web SDK

    Required

    Option 1: Add the JavaScript snippet to your HTML Recommended

    HTML
    <script>
        !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(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/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="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".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:'https://us.i.posthog.com', defaults:'2025-11-30'})
    </script>

    Option 2: Install via package manager

    npm install --save posthog-js

    And then include it with your project API key and host (which you can find in your project settings):

    Web
    import posthog from 'posthog-js'
    

    posthog.init('<ph_project_api_key>', {
      api_host: 'https://us.i.posthog.com',
      defaults: '2025-11-30'
    })

    See our framework specific docs for Next.js, React, Vue, Angular, Astro, Remix, and Svelte for more installation details.

    Bundle all required extensions (advanced)

    By default, the JavaScript Web library only loads the core functionality. It lazy-loads extensions such as surveys or the session replay 'recorder' when needed.

    This can cause issues if:

    • You have a Content Security Policy (CSP) that blocks inline scripts.
    • You want to optimize your bundle at build time to ensure all dependencies are ready immediately.
    • Your app is running in environments like the Chrome Extension store or Electron that reject or block remote code loading.

    To solve these issues, we have multiple import options available below.

    Note: With any of the no-external options, the toolbar will be unavailable as this is only possible as a runtime dependency loaded directly from us.posthog.com.

    Web
    // No external code loading possible (this disables all extensions such as Replay, Surveys, Exceptions etc.)
    import posthog from 'posthog-js/dist/module.no-external'
    

    // No external code loading possible but all external dependencies pre-bundled
    import posthog from 'posthog-js/dist/module.full.no-external'
    

    // All external dependencies pre-bundled and with the ability to load external scripts (primarily useful is you use Site Apps)
    import posthog from 'posthog-js/dist/module.full'
    

    // Finally you can also import specific extra dependencies 
    import "posthog-js/dist/recorder"
    import "posthog-js/dist/surveys"
    import "posthog-js/dist/exception-autocapture"
    import "posthog-js/dist/tracing-headers"
    import "posthog-js/dist/web-vitals"
    import posthog from 'posthog-js/dist/module.no-external'
    

    // All other posthog commands are the same as usual
    posthog.init('<ph_project_api_key>', { api_host: 'https://us.i.posthog.com', defaults: '2025-11-30' })

    Note: You should ensure if using this option that you always import posthog-js from the same module, otherwise multiple bundles could get included. At this time @posthog/react does not work with any module import other than the default.

    Don't want to send test data while developing?

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

    Web
    if (!window.location.host.includes('127.0.0.1') && !window.location.host.includes('localhost')) {
        posthog.init('<ph_project_api_key>', { api_host: 'https://us.i.posthog.com', defaults: '2025-11-30' })
    }
    What is the `defaults` option?

    The defaults is a date, such as 2025-11-30, for a configuration snapshot used as defaults to initialize PostHog. This default is overridden when you explicitly set a value for any of the options.

  2. Capture conversion event

    Required

    Once PostHog is initialized, you should be able to capture events. For your experiment to be meaningful, we need to capture an event that we want to measure, such as a conversion event.

    For this tutorial, let's capture a conversion event on a <button id="cta"> click.

    Web
    <button id="cta">Click me</button>
    

    <script>
      document.getElementById('cta').addEventListener('click', () => {
        posthog.capture('cta clicked')
      })
    </script>

  3. Validate PostHog events

    Checkpoint
    Confirm events are being sent to PostHog

    Before proceeding, let's make sure events are being captured and sent to PostHog. You should see cta clicked events appear in the Activity feed.

    Check for events in PostHog

  4. Create an experiment

    Required

    Go to the Experiments tab in the PostHog app and click on the New experiment button in the top right.

    Create experiment

    For this tutorial, let's create a new experiment using simplified test values:

    • Name: "Test experiment"
    • Description: "This is a test experiment"
    • Feature flag key: "test-experiment-ff-key"
    • Experiment type: "Feature flag"
    • Variants: "control" and "test"
    • Participant type: "Users"

    Then click Save as draft.

  5. Add primary metric and launch

    Required

    Scroll down to the Primary metrics section and click + Add primary metric.

    Choose Single-use and select Type > Mean.

    Then search for the event cta clicked under Metric and click Save.

    Add primary metric

    By default, experiments are exposed to 100% of users. You can customize release conditions to expose the experiment to a subset of users.

    For this tutorial, we'll ship the experiment to all users and click Launch in the top right.

  6. Call feature flag

    Required

    Use the PostHog SDK to call the experiment flag and change the <button id="cta"> text based on the assigned variant.

    Web
    // Ensure flags are loaded before usage.
    // You only need to call this on the code the first time a user visits.
    // See this doc for more details: /docs/feature-flags/manual#ensuring-flags-are-loaded-before-usage
    posthog.onFeatureFlags(function() {
      const cta = document.getElementById('cta')
      const variant = posthog.getFeatureFlag('test-experiment-ff-key')
      cta.textContent = variant == 'control' ? 'Control CTA' : 'Test CTA'
    })
    

    // Otherwise, you can just do:
    const cta = document.getElementById('cta')
    const variant = posthog.getFeatureFlag('test-experiment-ff-key')
    cta.textContent = variant == 'control' ? 'Control CTA' : 'Test CTA'
    

    // You can also test your code by overriding the feature flag:
    // e.g., posthog.featureFlags.overrideFeatureFlags({ flags: {'test-experiment-ff-key': 'test'}})

    Now when a user triggers a cta clicked event, PostHog automatically assigns the user to a variant and records an experiment exposure.

    By default, users are split equally between variants. If you want to assign specific users to a specific variant, see more about distribution and release conditions.

  7. Validate feature flag calls

    Checkpoint

    Make sure exposures and feature flag calls are being sent to PostHog. You should see $feature_flag_called events appear in the Activity feed.

    Check for events in PostHog

  8. Evaluate experiment results

    Recommended

    As you capture more cta clicked events, more exposures will populate the primary metrics in your experiment.

    Evaluate experiment metrics

    With enough data, you can analyze the experiment and its variants by:

    • Conversion rates
    • Statistical significance
    • Credible intervals
    • Chance to win %
    • Minimum detectable effect
    • And more

Community questions

Was this page useful?

Questions about this page? or post a community question.