User properties

Last updated:

User properties enable you to capture, manage, and analyze specific data about a user. You can use them to create filters or cohorts, which can then be used in insights, feature flags, and more.

How to set user properties

The recommended way to set user properties is to include them when capturing an event:

posthog.capture(
'event_name',
{
$set: { name: 'Max Hedgehog' },
$set_once: { initial_url: '/blog' },
}
)

You can also set user properties when you call the identify method:

posthog.identify(
'distinct_id',
{ email: 'max@hedgehogmail.com', name: 'Max Hedgehog' }
{},
);

User property values can be strings, booleans, numbers, objects, or arrays. For objects and arrays, you can use HogQL to access nested properties in the PostHog app.

Note that user properties are set in the order the events are ingested, and not according to event timestamps. Since we typically ingest events as soon as we receive them, you only need to take this into consideration when you're importing historical data.

What is the difference between set and set_once?

When using set, it will replace any value that may have been set on a person for a specific property. In contrast, set_once will only set the property if it has never been set before.

set is typically used for properties that may change over time – e.g., email, current plan, organization name. set_once is typically only used for information that is guaranteed to never change – e.g., the first URL a user visited, or the date a user first logged in.

For example:

posthog.capture(
'event_name',
{
$set: { name: 'Max Hedgehog' },
$set_once: { initial_url: '/blog' },
}
)
posthog.capture(
'event_name',
{
$set: { name: 'Mr. Fox' },
$set_once: { initial_url: '/pricing' },
}
)
// name: 'Mr. Fox'
// initial_url: '/blog'

How to remove user properties

Similarly to how you set properties, you can use $unset to remove properties with any event and including an array of properties keys:

posthog.capture(
'event_name',
{
$unset: ['email'],
}
)

How to set group properties

In the same way that every user can have properties associated with them, every group can have properties associated with it. You can find details on how to set group properties in the groups docs.

How to view user properties

To view properties for a particular user, go to "Persons & Groups" in the PostHog app. Then, click on any person in the list to view their properties.

On a user's property list, you can add properties to them by clicking the "New property" button, then adding a key, type, and value. You can also delete a custom property for a user by clicking the red garbage bin icon on the right side of property listing.

Person display name

The person display name is the name that is shown in the PostHog UI. The person properties that are used as the display name can be configured in Project Settings.

Where to change the display name in project settings

Default user properties

The following properties are automatically set for all users when using the posthog-js library or JavaScript snippet:

PropertyProperty NameDescriptionExample
utm_campaignUTM CampaignUTM campaign tag (last-touch).feature launch, discount
utm_contentUTM ContentUTM content tag (last-touch).bottom link, second button
utm_mediumUTM MediumUTM medium tag (last-touch).Social, Organic, Paid, Email
utm_sourceUTM SourceUTM source tag (last-touch).Google, Bing, Twitter, Facebook
$browserBrowserName of the browser the user has used.Chrome, Firefox
$browser_versionBrowser VersionThe version of the browser that was used. Used in combination with Browser.70, 79
$initial_browserInitial BrowserName of the browser the user first used (first-touch).Chrome, Firefox
$initial_browser_versionInitial Browser VersionThe version of the browser that the user first used (first-touch). Used in combination with Browser.70, 79
$initial_current_urlInitial Current URLThe first URL the user visited, including all the trimings.https://example.com/interesting-article?parameter=true
$initial_device_typeInitial Device TypeThe initial type of device that was used (first-touch).Mobile, Tablet, Desktop
$initial_osInitial OSThe operating system that the user first used (first-touch).Windows, Mac OS X
$initial_pathnameInitial Path NameThe path of the Current URL, which means everything in the url after the domain. Data from the first time this user was seen./pricing, /about-us/team
$initial_referrerInitial Referrer URLURL of where the user came from most recently (last-touch). Data from the first time this user was seen.https://google.com/search?q=posthog&rlz=1C...
$initial_referring_domainInitial Referring DomainDomain of where the user came from most recently (last-touch). Data from the first time this user was seen.google.com, facebook.com
$initial_utm_campaignInitial UTM CampaignUTM campaign tag (first-touch).feature launch, discount
$initial_utm_contentInitial UTM ContentUTM content tag (first-touch).bottom link, second button
$initial_utm_mediumInitial UTM MediumUTM medium tag (first-touch).Social, Organic, Paid, Email
$initial_utm_sourceInitial UTM SourceUTM source tag (first-touch).Google, Bing, Twitter, Facebook
$osOSThe operating system of the user.Windows, Mac OS X
$referrerReferrer URLURL of where the user came from most recently (last-touch).https://google.com/search?q=posthog&rlz=1C...
$referring_domainReferring DomainDomain of where the user came from most recently (last-touch).google.com, facebook.com

GeoIP Properties

By default, the GeoIP plugin is turned on for all PostHog projects. This adds the following properties to all events.

PropertyProperty NameDescriptionExample
$geoip_city_nameCity NameName of the city matched to this event's IP address.Sydney, Chennai, Brooklyn
$geoip_continent_codeContinent CodeCode of the continent matched to this event's IP address.OC, AS, NA
$geoip_continent_nameContinent NameName of the continent matched to this event's IP address.Oceania, Asia, North America
$geoip_country_codeCountry CodeCode of the country matched to this event's IP address.AU, IN, US
$geoip_country_nameCountry NameName of the country matched to this event's IP address.Australia, India, United States
$geoip_latitudeLatitudeApproximated latitude matched to this event's IP address.-33.8591, 13.1337, 40.7
$geoip_longitudeLongitudeApproximated longitude matched to this event's IP address.151.2, 80.8008, -73.9
$geoip_postal_codePostal CodeApproximated postal code matched to this event's IP address.2000, 600004, 11211
$geoip_subdivision_1_codeSubdivision 1 CodeCode of the subdivision matched to this event's IP address.NSW, TN, NY
$geoip_subdivision_1_nameSubdivision 1 NameName of the subdivision matched to this event's IP address.New South Wales, Tamil Nadu, New York
$geoip_subdivision_2_codeSubdivision 2 CodeCode of the second subdivision matched to this event's IP address.
$geoip_subdivision_2_nameSubdivision 2 NameName of the second subdivision matched to this event's IP address.
$geoip_time_zoneTimezoneTimezone matched to this event's IP address.Australia/Sydney, Asia/Kolkata, America/New_York
$initial_geoip_city_nameInitial City NameName of the city matched to this event's IP address. Data from the first time this user was seen.Sydney, Chennai, Brooklyn
$initial_geoip_continent_codeInitial Continent CodeCode of the continent matched to this event's IP address. Data from the first time this user was seen.OC, AS, NA
$initial_geoip_continent_nameInitial Continent NameName of the continent matched to this event's IP address. Data from the first time this user was seen.Oceania, Asia, North America
$initial_geoip_country_codeInitial Country CodeCode of the country matched to this event's IP address. Data from the first time this user was seen.AU, IN, US
$initial_geoip_country_nameInitial Country NameName of the country matched to this event's IP address. Data from the first time this user was seen.Australia, India, United States
$initial_geoip_latitudeInitial LatitudeApproximated latitude matched to this event's IP address. Data from the first time this user was seen.-33.8591, 13.1337, 40.7
$initial_geoip_subdivision_1_codeInitial Subdivision 1 CodeCode of the subdivision matched to this event's IP address. Data from the first time this user was seen.NSW, TN, NY
$initial_geoip_longitudeInitial LongitudeApproximated longitude matched to this event's IP address. Data from the first time this user was seen.151.2, 80.8008, -73.9
$initial_geoip_postal_codeInitial Postal CodeApproximated postal code matched to this event's IP address. Data from the first time this user was seen.2000, 600004, 11211
$initial_geoip_subdivision_1_nameInitial Subdivision 1 NameName of the subdivision matched to this event's IP address. Data from the first time this user was seen.New South Wales, Tamil Nadu, New York
$initial_geoip_subdivision_2_codeInitial Subdivision 2 CodeCode of the second subdivision matched to this event's IP address. Data from the first time this user was seen.
$initial_geoip_subdivision_2_nameInitial Subdivision 2 NameName of the second subdivision matched to this event's IP address. Data from the first time this user was seen.
$initial_geoip_time_zoneInitial TimezoneTimezone matched to this event's IP address. Data from the first time this user was seen.Australia/Sydney, Asia/Kolkata, America/New_York

Questions?

Was this page useful?

Next article

UTM segmentation

UTM parameters are a set 5 five parameters that allow you to track the effectiveness of marketing campaigns across traffic sources. These parameters were first introduced by Google Analytics, but are now a common way to identify where traffic to your website is coming from. They are especially useful when running ad campaigns, as nearly every platform will set them when sending traffic to your website. The parameters are attached to a link using query parameters, for example: https://www.example…

Read next article