Welcome to the PostHog Package Docs
If you find anything wrong or missing from these docs, please report the issue here!
Getting Started
This package is made to work with an app provider, or whatever you use to wrap all your pages. Just drop it in at the top level.
You don’t need to call the load event before using any of the actions. The callback will wait for PostHog to be ready, so you can use these anywhere inside your wrapper.
Want to see it in action? There’s a video above that gives you the quick tour.
Load
Initializes the PostHog analytics SDK in the browser. Loads the SDK with your API key and configuration, sets sensible defaults, and triggers a 'Ready' event when PostHog is available.
Parameters
| Parameter | Usage |
|---|---|
| key | Your PostHog project API key. This is required. |
| region | The PostHog region to use (e.g., 'us', 'eu'). Defaults to 'us' if not provided, which sets the API host to https://us.i.posthog.com. |
| personProfiles | Controls when person profiles are enabled. Defaults to 'always' if not specified. |
| apiHost | Custom API host URL. If not provided, it is derived from the region. |
| options | Additional PostHog configuration options as a plain object. Ignored if not a valid object. |
Events
| Event | Description |
|---|---|
| Ready | Fires when PostHog is fully loaded and ready to use. |
Alias
Links two distinct user identities in PostHog, typically when a user signs up or logs in, so their activity is merged under a single profile.
Parameters
| Parameter | Usage |
|---|---|
| newDistinctId | The new unique identifier for the user. |
| oldDistinctId | The previous unique identifier for the user. |
Events
| Event | Description |
|---|---|
| Aliased | Fires when the aliasing operation is complete. |
Error
Captures an error in PostHog, optionally with additional properties for context.
Parameters
| Parameter | Usage |
|---|---|
| errorName | The name or message of the error to capture (required, string). |
| props | Optional object with key-value pairs for additional error properties. |
Events
| Event | Description |
|---|---|
| Error Captured | Fires when the error has been successfully sent to PostHog. |
Event
Captures a custom event in PostHog, optionally with properties for additional context.
Parameters
| Parameter | Usage |
|---|---|
| eventName | The name of the event to capture (required, string). |
| properties | Optional object with key-value pairs for event properties. |
Events
| Event | Description |
|---|---|
| Event Captured | Fires when the event has been successfully sent to PostHog. |
Get Distinct Id
Retrieves the current user's unique PostHog distinct ID and returns it in the event payload.
Events
| Event | Description |
|---|---|
| Id | Fires when the distinct ID is retrieved. Returns an object: {id: string}. |
Group
Associates a user with a group in PostHog, such as a company or team, using a group type and key. Optionally attaches properties to the group.
Parameters
| Parameter | Usage |
|---|---|
| groupType | The type of group (e.g., 'company', 'team'). Required, string. |
| groupKey | The unique identifier for the group. Required, string. |
| properties | Optional object with key-value pairs for group properties. |
Events
| Event | Description |
|---|---|
| Grouped | Fires when the user has been successfully associated with the group. |
Identify
Identifies a user in PostHog with a unique ID and optional properties.
Parameters
| Parameter | Usage |
|---|---|
| id | The unique identifier for the user. Required, string. |
| properties | Optional object with key-value pairs for user properties. |
Events
| Event | Description |
|---|---|
| Identified | Fires when the user has been successfully identified. |
Opt In
Enables PostHog event capturing for the current user, allowing analytics data to be collected.
Events
| Event | Description |
|---|---|
| Opted In | Fires when the user has successfully opted in to event capturing. |
Opt Out
Disables PostHog event capturing for the current user, preventing analytics data from being collected.
Events
| Event | Description |
|---|---|
| Opted Out | Fires when the user has successfully opted out of event capturing. |
Reset
Resets the PostHog user identity and clears any stored analytics data for the current user.
Events
| Event | Description |
|---|---|
| Reset | Fires when the user's PostHog identity and data have been reset. |
Set
Sets or sets-once user properties in PostHog People analytics. Use 'setProps' to update properties and 'setOnceProps' to set properties only if they haven't been set before.
Parameters
| Parameter | Usage |
|---|---|
| setProps | Object of properties to set or update for the user. |
| setOnceProps | Object of properties to set only if they are not already set for the user. |
Events
| Event | Description |
|---|---|
| Set | Fires when the user properties have been updated. |