PostHog JavaScript Web SDK

SDK Version: 1.260.1

|

PostHog

This is the SDK reference for the PostHog JavaScript Web SDK. You can learn more about example usage in the JavaScript Web SDK documentation. You can also follow framework specific guides to integrate PostHog into your project.

This SDK is designed for browser environments. Use the PostHog Node.js SDK for server-side usage.

Initialization methods

debugpublic

Enables or disables debug mode for detailed logging.

Notes:

Debug mode logs all PostHog calls to the browser console for troubleshooting. Can also be enabled by adding ?__posthog_debug=true to the URL.

Parameters

NameType
debug?boolean

If true, will enable debug mode.

Examples

typescript
// enable debug mode
posthog.debug(true)

Returns

Type
void

getPageViewIdpublic

Returns the current page view ID.

Examples

typescript
// Generated example for getPageViewId
posthog.getPageViewId();

Returns

Type
Union ofstring
undefined

initpublic

Initializes a new instance of the PostHog capturing object.

Notes:

All new instances are added to the main posthog object as sub properties (such as posthog.library_name) and also returned by this function. Learn more about configuration options

Parameters

NameType
tokenstring

Your PostHog API token

config?OnlyValidKeys<Partial<PostHogConfig>, Partial<PostHogConfig>>

A dictionary of config options to override

name?string

The name for the new posthog instance that you want created

Examples

typescript
// basic initialization
posthog.init('<ph_project_api_key>', {
api_host: 'https://us.i.posthog.com'
})

Returns

Type
PostHog

set_configpublic

Updates the configuration of the PostHog instance.

Parameters

NameType
configPartial<PostHogConfig>

A dictionary of new configuration values to update

Examples

typescript
// Generated example for set_config
posthog.set_config();

Returns

Type
void

Capture methods

capturepublic

Captures an event with optional properties and configuration.

Notes:

You can capture arbitrary object-like values as events. Learn about capture best practices

Parameters

NameType
event_nameEventName

The name of the event (e.g., 'Sign Up', 'Button Click', 'Purchase')

properties?Properties | null

Properties to include with the event describing the user or event details

options?CaptureOptions

Optional configuration for the capture request

Examples

typescript
// basic event capture
posthog.capture('cta-button-clicked', {
button_name: 'Get Started',
page: 'homepage'
})

Returns

Type
Union ofCaptureResult
undefined

register_for_sessionpublic

Registers super properties for the current session only.

Notes:

Session super properties are automatically added to all events during the current browser session. Unlike regular super properties, these are cleared when the session ends and are stored in sessionStorage.

Parameters

NameType
propertiesProperties

An associative array of properties to store about the user

Examples

typescript
// register session-specific properties
posthog.register_for_session({
current_page_type: 'checkout',
ab_test_variant: 'control'
})

Returns

Type
void

register_oncepublic

Registers super properties only if they haven't been set before.

Notes:

Unlike register(), this method will not overwrite existing super properties. Use this for properties that should only be set once, like signup date or initial referrer.

Parameters

NameType
propertiesProperties

An associative array of properties to store about the user

default_value?Property

Value to override if already set in super properties (ex: 'False') Default: 'None'

days?number

How many days since the users last visit to store the super properties

Examples

typescript
// register once-only properties
posthog.register_once({
first_login_date: new Date().toISOString(),
initial_referrer: document.referrer
})

Returns

Type
void

registerpublic

Registers super properties that are included with all events.

Notes:

Super properties are stored in persistence and automatically added to every event you capture. These values will overwrite any existing super properties with the same keys.

Parameters

NameType
propertiesProperties

properties to store about the user

days?number

How many days since the user's last visit to store the super properties

Examples

typescript
// register a single property
posthog.register({ plan: 'premium' })

Returns

Type
void

unregister_for_sessionpublic

Removes a session super property from the current session.

Notes:

This will stop the property from being automatically included in future events for this session. The property is removed from sessionStorage.

Parameters

NameType
propertystring

The name of the session super property to remove

Examples

typescript
// remove a session property
posthog.unregister_for_session('current_flow')

Returns

Type
void

unregisterpublic

Removes a super property from persistent storage.

Notes:

This will stop the property from being automatically included in future events. The property will be permanently removed from the user's profile.

Parameters

NameType
propertystring

The name of the super property to remove

Examples

typescript
// remove a super property
posthog.unregister('plan_type')

Returns

Type
void

Error tracking methods

captureExceptionpublic

Capture a caught exception manually

Parameters

NameType
errorunknown

The error to capture

additionalProperties?Properties

Any additional properties to add to the error event

Examples

typescript
// Capture a caught exception
try {
// something that might throw
} catch (error) {
posthog.captureException(error)
}

Returns

Type
Union ofCaptureResult
undefined

Events methods

onpublic

Exposes a set of events that PostHog will emit. e.g. eventCaptured is emitted immediately before trying to send an event

Unlike onFeatureFlags and onSessionId these are not called when the listener is registered, the first callback will be the next event after registering a listener

Parameters

NameType
event'eventCaptured'

The event to listen for.

cb(...args: any[]) => void

The callback function to call when the event is emitted.

Examples

typescript
posthog.on('eventCaptured', (event) => {
console.log(event)
})

Returns

Type
() => void

Feature flags methods

getEarlyAccessFeaturespublic

Get the list of early access features. To check enrollment status, use isFeatureEnabled. Learn more in the docs

Parameters

NameType
callbackEarlyAccessFeatureCallback

The callback function will be called when the early access features are loaded.

force_reload?boolean

Whether to force a reload of the early access features.

stages?EarlyAccessFeatureStage[]

The stages of the early access features to load.

Examples

typescript
const posthog = usePostHog()
const activeFlags = useActiveFeatureFlags()
const [activeBetas, setActiveBetas] = useState([])
const [inactiveBetas, setInactiveBetas] = useState([])
const [comingSoonFeatures, setComingSoonFeatures] = useState([])
useEffect(() => {
posthog.getEarlyAccessFeatures((features) => {
// Filter features by stage
const betaFeatures = features.filter(feature => feature.stage === 'beta')
const conceptFeatures = features.filter(feature => feature.stage === 'concept')
setComingSoonFeatures(conceptFeatures)
if (!activeFlags || activeFlags.length === 0) {
setInactiveBetas(betaFeatures)
return
}
const activeBetas = betaFeatures.filter(
beta => activeFlags.includes(beta.flagKey)
);
const inactiveBetas = betaFeatures.filter(
beta => !activeFlags.includes(beta.flagKey)
);
setActiveBetas(activeBetas)
setInactiveBetas(inactiveBetas)
}, true, ['concept', 'beta'])
}, [activeFlags])

Returns

Type
void

getFeatureFlagpublic

Gets the value of a feature flag for the current user.

Notes:

Returns the feature flag value which can be a boolean, string, or undefined. Supports multivariate flags that can return custom string values.

Parameters

NameType
keystring
options?{ send_event?: boolean; }

(optional) If send_event: false, we won't send an $feature_flag_call event to PostHog.

Examples

typescript
// check boolean flag
if (posthog.getFeatureFlag('new-feature')) {
// show new feature
}

Returns

Type
Union ofboolean
string
undefined

getFeatureFlagPayloadpublic

Get feature flag payload value matching key for user (supports multivariate flags).

Parameters

NameType
keystring

Examples

typescript
if(posthog.getFeatureFlag('beta-feature') === 'some-value') {
const someValue = posthog.getFeatureFlagPayload('beta-feature')
// do something
}

Returns

isFeatureEnabledpublic

Checks if a feature flag is enabled for the current user.

Notes:

Returns true if the flag is enabled, false if disabled, or undefined if not found. This is a convenience method that treats any truthy value as enabled.

Parameters

NameType
keystring
options?{ send_event: boolean; }

(optional) If send_event: false, we won't send an $feature_flag_call event to PostHog.

Examples

typescript
// simple feature flag check
if (posthog.isFeatureEnabled('new-checkout')) {
showNewCheckout()
}

Returns

Type
Union ofboolean
undefined

onFeatureFlagspublic

Register an event listener that runs when feature flags become available or when they change. If there are flags, the listener is called immediately in addition to being called on future changes. Note that this is not called only when we fetch feature flags from the server, but also when they change in the browser.

Parameters

NameType
callbackFeatureFlagsCallback

The callback function will be called once the feature flags are ready or when they are updated. It'll return a list of feature flags enabled for the user, the variants, and also a context object indicating whether we succeeded to fetch the flags or not.

Examples

typescript
posthog.onFeatureFlags(function(featureFlags, featureFlagsVariants, { errorsLoading }) {
// do something
})

Returns

Type
() => void

reloadFeatureFlagspublic

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

Examples

typescript
posthog.reloadFeatureFlags()

Returns

Type
void

resetGroupPropertiesForFlagspublic

Resets the group properties for feature flags.

Parameters

NameType
group_type?string

Examples

typescript
posthog.resetGroupPropertiesForFlags()

Returns

Type
void

resetPersonPropertiesForFlagspublic

Resets the person properties for feature flags.

Examples

typescript
posthog.resetPersonPropertiesForFlags()

Returns

Type
void

setGroupPropertiesForFlagspublic

Set override group properties for feature flags. This is used when dealing with new groups / where you don't want to wait for ingestion to update properties. Takes in an object, the key of which is the group type.

Parameters

NameType
properties{ [type: string]: Properties; }

The properties to override, the key of which is the group type.

reloadFeatureFlags?boolean

Whether to reload feature flags.

Examples

typescript
// Set properties with reload
posthog.setGroupPropertiesForFlags({'organization': { name: 'CYZ', employees: '11' } })

Returns

Type
void

setPersonPropertiesForFlagspublic

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:

Parameters

NameType
propertiesProperties

The properties to override.

reloadFeatureFlags?boolean

Whether to reload feature flags.

Examples

typescript
// Set properties
posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'})

Returns

Type
void

updateEarlyAccessFeatureEnrollmentpublic

Opt the user in or out of an early access feature. Learn more in the docs

Parameters

NameType
keystring

The key of the feature flag to update.

isEnrolledboolean

Whether the user is enrolled in the feature.

stage?string

The stage of the feature flag to update.

Examples

typescript
const toggleBeta = (betaKey) => {
if (activeBetas.some(
beta => beta.flagKey === betaKey
)) {
posthog.updateEarlyAccessFeatureEnrollment(
betaKey,
false
)
setActiveBetas(
prevActiveBetas => prevActiveBetas.filter(
item => item.flagKey !== betaKey
)
);
return
}
posthog.updateEarlyAccessFeatureEnrollment(
betaKey,
true
)
setInactiveBetas(
prevInactiveBetas => prevInactiveBetas.filter(
item => item.flagKey !== betaKey
)
);
}
const registerInterest = (featureKey) => {
posthog.updateEarlyAccessFeatureEnrollment(
featureKey,
true
)
// Update UI to show user has registered
}

Returns

Type
void

Identification methods

aliaspublic

Creates an alias linking two distinct user identifiers. Learn more about identifying users

Notes:

PostHog will use this to link two distinct_ids going forward (not retroactively). Call this when a user signs up to connect their anonymous session with their account.

Parameters

NameType
aliasstring

A unique identifier that you want to use for this user in the future.

original?string

The current identifier being used for this user.

Examples

typescript
// link anonymous user to account on signup
posthog.alias('user_12345')

Returns

Type
Union ofCaptureResult
void
number

createPersonProfilepublic

Creates a person profile for the current user, if they don't already have one and config.person_profiles is set to 'identified_only'. Produces a warning and does not create a profile if config.person_profiles is set to 'never'. Learn more about person profiles

Examples

typescript
posthog.createPersonProfile()

Returns

Type
void

get_distinct_idpublic

Returns the current distinct ID for the user.

Notes:

This is either the auto-generated ID or the ID set via identify(). The distinct ID is used to associate events with users in PostHog.

Examples

typescript
// get the current user ID
const userId = posthog.get_distinct_id()
console.log('Current user:', userId)

Returns

Type
string

get_propertypublic

Returns the value of a super property. Returns undefined if the property doesn't exist.

Notes:

get_property() can only be called after the PostHog library has finished loading. init() has a loaded function available to handle this automatically.

Parameters

NameType
property_namestring

The name of the super property you want to retrieve

Examples

typescript
// grab value for '$user_id' after the posthog library has loaded
posthog.init('<YOUR PROJECT TOKEN>', {
loaded: function(posthog) {
user_id = posthog.get_property('$user_id');
}
});

Returns

Type
Union ofProperty
undefined

getGroupspublic

Returns the current groups.

Examples

typescript
// Generated example for getGroups
posthog.getGroups();

Returns

Type
Record<string, any>

getSessionPropertypublic

Returns the value of the session super property named property_name. If no such property is set, getSessionProperty() will return the undefined value.

Notes:

This is based on browser-level sessionStorage, NOT the PostHog session. getSessionProperty() can only be called after the PostHog library has finished loading. init() has a loaded function available to handle this automatically.

Parameters

NameType
property_namestring

The name of the session super property you want to retrieve

Examples

typescript
// grab value for 'user_id' after the posthog library has loaded
posthog.init('YOUR PROJECT TOKEN', {
loaded: function(posthog) {
user_id = posthog.getSessionProperty('user_id');
}
});

Returns

Type
Union ofProperty
undefined

grouppublic

Associates the user with a group for group-based analytics. Learn more about groups

Notes:

Groups allow you to analyze users collectively (e.g., by organization, team, or account). This sets the group association for all subsequent events and reloads feature flags.

Parameters

NameType
groupTypestring

Group type (example: 'organization')

groupKeystring

Group key (example: 'org::5')

groupPropertiesToSet?Properties

Optional properties to set for group

Examples

typescript
// associate user with an organization
posthog.group('organization', 'org_12345', {
name: 'Acme Corp',
plan: 'enterprise'
})

Returns

Type
void

identifypublic

Associates a user with a unique identifier instead of an auto-generated ID. Learn more about identifying users

Notes:

By default, PostHog assigns each user a randomly generated distinct_id. Use this method to replace that ID with your own unique identifier (like a user ID from your database).

Parameters

NameType
new_distinct_id?string

A string that uniquely identifies a user. If not provided, the distinct_id currently in the persistent store (cookie or localStorage) will be used.

userPropertiesToSet?Properties

Optional: An associative array of properties to store about the user. Note: For feature flag evaluations, if the same key is present in the userPropertiesToSetOnce, it will be overwritten by the value in userPropertiesToSet.

userPropertiesToSetOnce?Properties

Optional: An associative array of properties to store about the user. If property is previously set, this does not override that value.

Examples

typescript
// basic identification
posthog.identify('user_12345')

Returns

Type
void

onSessionIdpublic

Register an event listener that runs whenever the session id or window id change. If there is already a session id, the listener is called immediately in addition to being called on future changes.

Can be used, for example, to sync the PostHog session id with a backend session.

Parameters

NameType
callbackSessionIdChangedCallback

The callback function will be called once a session id is present or when it or the window id are updated.

Examples

typescript
posthog.onSessionId(function(sessionId, windowId) { // do something })

Returns

Type
() => void

resetpublic

Resets all user data and starts a fresh session.

⚠️ Warning: Only call this when a user logs out. Calling at the wrong time can cause split sessions.

This clears: - Session ID and super properties - User identification (sets new random distinct_id) - Cached data and consent settings

Parameters

NameType
reset_device_id?boolean

Examples

typescript
// reset on user logout
function logout() {
posthog.reset()
// redirect to login page
}

Returns

Type
void

resetGroupspublic

Resets only the group properties of the user currently logged in. Learn more about groups

Examples

typescript
posthog.resetGroups()

Returns

Type
void

setPersonPropertiespublic

Sets properties on the person profile associated with the current distinct_id. Learn more about identifying users

Notes:

Updates user properties that are stored with the person profile in PostHog. If person_profiles is set to identified_only and no profile exists, this will create one.

Parameters

NameType
userPropertiesToSet?Properties

Optional: An associative array of properties to store about the user. Note: For feature flag evaluations, if the same key is present in the userPropertiesToSetOnce, it will be overwritten by the value in userPropertiesToSet.

userPropertiesToSetOnce?Properties

Optional: An associative array of properties to store about the user. If property is previously set, this does not override that value.

Examples

typescript
// set user properties
posthog.setPersonProperties({
email: 'user@example.com',
plan: 'premium'
})

Returns

Type
void

LLM analytics methods

captureTraceFeedbackpublic

Capture written user feedback for a LLM trace. Numeric values are converted to strings.

Parameters

NameType
traceIdstring | number

The trace ID to capture feedback for.

userFeedbackstring

The feedback to capture.

Examples

typescript
// Generated example for captureTraceFeedback
posthog.captureTraceFeedback();

Returns

Type
void

captureTraceMetricpublic

Capture a metric for a LLM trace. Numeric values are converted to strings.

Parameters

NameType
traceIdstring | number

The trace ID to capture the metric for.

metricNamestring

The name of the metric to capture.

metricValuestring | number | boolean

The value of the metric to capture.

Examples

typescript
// Generated example for captureTraceMetric
posthog.captureTraceMetric();

Returns

Type
void

Privacy methods

clear_opt_in_out_capturingpublic

Clear the user's opt in/out status of data capturing and cookies/localstorage for this PostHog instance

Examples

typescript
// Generated example for clear_opt_in_out_capturing
posthog.clear_opt_in_out_capturing();

Returns

Type
void

has_opted_in_capturingpublic

Checks if the user has opted into data capturing.

Notes:

Returns the current consent status for event tracking and data persistence.

Examples

typescript
if (posthog.has_opted_in_capturing()) {
// show analytics features
}

Returns

Type
boolean

has_opted_out_capturingpublic

Checks if the user has opted out of data capturing.

Notes:

Returns the current consent status for event tracking and data persistence.

Examples

typescript
if (posthog.has_opted_out_capturing()) {
// disable analytics features
}

Returns

Type
boolean

is_capturingpublic

Checks whether the PostHog library is currently capturing events.

Usually this means that the user has not opted out of capturing, but the exact behaviour can be controlled by some config options.

Additionally, if the cookieless_mode is set to 'on_reject', we will capture events in cookieless mode if the user has explicitly opted out.

Examples

typescript
// Generated example for is_capturing
posthog.is_capturing();

Returns

Type
boolean

opt_in_capturingpublic

Opts the user into data capturing and persistence.

Notes:

Enables event tracking and data persistence (cookies/localStorage) for this PostHog instance. By default, captures an $opt_in event unless disabled.

Parameters

NameType
options?{ captureEventName?: EventName | null | false; /** event name to be used for capturing the opt-in action */ captureProperties?: Properties; /** set of properties to be captured along with the opt-in action */ }

Examples

typescript
// simple opt-in
posthog.opt_in_capturing()

Returns

Type
void

opt_out_capturingpublic

Opts the user out of data capturing and persistence.

Notes:

Disables event tracking and data persistence (cookies/localStorage) for this PostHog instance. If opt_out_persistence_by_default is true, SDK persistence will also be disabled.

Examples

typescript
// opt user out (e.g., on privacy settings page)
posthog.opt_out_capturing()

Returns

Type
void

Session replay methods

get_session_idpublic

Returns the current session_id.

Notes:

This should only be used for informative purposes. Any actual internal use case for the session_id should be handled by the sessionManager.

Examples

typescript
// Generated example for get_session_id
posthog.get_session_id();

Returns

Type
string

get_session_replay_urlpublic

Returns the Replay url for the current session.

Parameters

NameType
options?{ withTimestamp?: boolean; timestampLookBack?: number; }

Options for the url

Examples

typescript
// basic usage
posthog.get_session_replay_url()
@example
js // timestamp posthog.get_session_replay_url({ withTimestamp: true })
@example
js // timestamp and lookback posthog.get_session_replay_url({ withTimestamp: true, timestampLookBack: 30 // look back 30 seconds }) ```

Returns

Type
string

sessionRecordingStartedpublic

returns a boolean indicating whether session recording is currently running

Examples

typescript
// Stop session recording if it's running
if (posthog.sessionRecordingStarted()) {
posthog.stopSessionRecording()
}

Returns

Type
boolean

startSessionRecordingpublic

turns session recording on, and updates the config option disable_session_recording to false

Parameters

NameType
override?{ sampling?: boolean; linked_flag?: boolean; url_trigger?: true; event_trigger?: true; } | true

optional boolean to override the default sampling behavior - ensures the next session recording to start will not be skipped by sampling or linked_flag config. true is shorthand for sampling: true, linked_flag: true

Examples

typescript
// Start and ignore controls
posthog.startSessionRecording(true)

Returns

Type
void

stopSessionRecordingpublic

turns session recording off, and updates the config option disable_session_recording to true

Examples

typescript
// Stop session recording
posthog.stopSessionRecording()

Returns

Type
void

Surveys methods

canRenderSurveydeprecated

Checks the feature flags associated with this Survey to see if the survey can be rendered. This method is deprecated because it's synchronous and won't return the correct result if surveys are not loaded. Use canRenderSurveyAsync instead.

Parameters

NameType
surveyIdstring

The ID of the survey to check.

Examples

typescript
// Generated example for canRenderSurvey
posthog.canRenderSurvey();

Returns

Type
Union ofSurveyRenderReason
null

canRenderSurveyAsyncpublic

Checks the feature flags associated with this Survey to see if the survey can be rendered.

Parameters

NameType
surveyIdstring

The ID of the survey to check.

forceReload?boolean

If true, the survey will be reloaded from the server, Default: false

Examples

typescript
posthog.canRenderSurveyAsync(surveyId).then((result) => {
if (result.visible) {
// Survey can be rendered
console.log('Survey can be rendered')
} else {
// Survey cannot be rendered
console.log('Survey cannot be rendered:', result.disabledReason)
}
})

Returns

Type
Promise<SurveyRenderReason>

getActiveMatchingSurveyspublic

Get surveys that should be enabled for the current user. See fetching surveys documentation for more details.

Parameters

NameType
callbackSurveyCallback

The callback function will be called when the surveys are loaded or updated.

forceReload?boolean

Whether to force a reload of the surveys.

Examples

typescript
posthog.getActiveMatchingSurveys((surveys) => {
// do something
})

Returns

Type
void

getSurveyspublic

Get list of all surveys.

Parameters

NameType
callbackSurveyCallback

Function that receives the array of surveys

forceReload?boolean

Optional boolean to force an API call for updated surveys

Examples

typescript
function callback(surveys, context) {
// do something
}
posthog.getSurveys(callback, false)

Returns

Type
void

onSurveysLoadedpublic

Register an event listener that runs when surveys are loaded.

Callback parameters: - surveys: Survey[]: An array containing all survey objects fetched from PostHog using the getSurveys method - context: isLoaded: boolean, error?: string : An object indicating if the surveys were loaded successfully

Parameters

NameType
callbackSurveyCallback

The callback function will be called when surveys are loaded or updated.

Examples

typescript
posthog.onSurveysLoaded((surveys, context) => { // do something })

Returns

Type
() => void

renderSurveypublic

Although we recommend using popover surveys and display conditions, if you want to show surveys programmatically without setting up all the extra logic needed for API surveys, you can render surveys programmatically with the renderSurvey method.

This takes a survey ID and an HTML selector to render an unstyled survey.

Parameters

NameType
surveyIdstring

The ID of the survey to render.

selectorstring

The selector of the HTML element to render the survey on.

Examples

typescript
posthog.renderSurvey(coolSurveyID, '#survey-container')

Returns

Type
void

Toolbar methods

loadToolbarpublic

returns a boolean indicating whether the toolbar loaded

Parameters

NameType
paramsToolbarParams

Examples

typescript
// Generated example for loadToolbar
posthog.loadToolbar();

Returns

Type
boolean

Other methods

pushpublic

push() keeps the standard async-array-push behavior around after the lib is loaded. This is only useful for external integrations that do not wish to rely on our convenience methods (created in the snippet).

Parameters

NameType
itemSnippetArrayItem

A [function_name, args...] array to be executed

Examples

typescript
posthog.push(['register', { a: 'b' }]);

Returns

Type
void

Community questions

Was this page useful?