Session replay installation
Session replay enables you to record users navigating through your website or mobile app and play back the individual sessions to watch how real users use your product.
Step one: Install our JavaScript web library
If you already have our JavaScript library or snippet installed, you can skip this step.
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.
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.
Set up a reverse proxy (recommended)
We recommend setting up a reverse proxy, so that events are less likely to be intercepted by tracking blockers.
We have our own managed reverse proxy service included in the platform packages, which routes through our infrastructure and makes setting up your proxy easy.
If you don't want to use our managed service then there are several other options for creating a reverse proxy, including using Cloudflare, AWS Cloudfront, and Vercel.
Grouping products in one project (recommended)
If you have multiple customer-facing products (e.g. a marketing website + mobile app + web app), it's best to install PostHog on them all and group them in one project.
This makes it possible to track users across their entire journey (e.g. from visiting your marketing website to signing up for your product), or how they use your product across multiple platforms.
Include ES5 support (optional)
If you need ES5 support for example to track Internet Explorer 11 replace /static/array.js
in the snippet with /static/array.full.es5.js
Working with AI code editors?
If you’re working with AI code editors (like Lovable, Bolt.new, Replit, and others), it’s easy to install PostHog. Just give it this prompt: npx -y @posthog/wizard@latest
Option 2: Install via package manager
And then include it with your project API key and host (which you can find in your project settings):
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
.
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-js/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:
What is the `defaults` option?
The defaults
is a date, such as 2025-05-24
, 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.
Step two: Enable session recordings in your project settings
Enable session recordings in your PostHog Project Settings.


Once enabled, the library will start recording sessions by default.
They can be toggled off in the by setting the disable_session_recording: true
flag in the config.
Users who opt out of event capturing will not have their sessions recorded.
Note on using Segment's SDK: Session Replay does not work if you send data using Segment's SDK as this data is not collected. If you use Segment, you may want to add the PostHog library as well – (make sure to only send regular event data from one source).
How to ignore sensitive elements
You may want to hide sensitive text or elements in your replays. See our privacy controls docs for how to do this.
How to record sessions across different domains
PostHog automatically captures sessions across subdomains (e.g. posthog.com
and us.posthog.com
), but recording sessions across different domains (e.g. posthog.com
and hogflix.com
) requires a bit more setup.
To do this, you need to pass the session_id
from the first domain to the second domain (for example, as a URL parameter). You can get this value by calling posthog.get_session_id()
.
Below is an example of how this looks like in Next.js:
On the second domain, bootstrap the PostHog initialization using the session ID.
With this setup, PostHog tracks the user's session across domains and captures a single, combined replay.