Custom properties

Custom properties are key–value pairs you send with an event, such as author: alice, plan: pro or logged_in: yes. They show up in the Properties tab of your dashboard, and you can filter any report by a property value.

Send properties with a custom event

plausible('Download', { props: { format: 'pdf', title: 'Price list' } })

Or with tagged events (spaces as +):

<a href="/price-list.pdf" class="plausible-event-name=Download plausible-event-format=pdf">Price list</a>

Send properties with pageviews

Use the customProperties option to add properties to every event, including pageviews:

plausible.init({
  customProperties: { author: 'alice', section: 'blog' },
})

It can also be a function that receives the event name:

plausible.init({
  customProperties: (eventName) => eventName === 'pageview' ? { logged_in: String(isLoggedIn()) } : {},
})

With the legacy script.pageview-props.js script, add event-<name> attributes to the script tag instead, for example event-author="alice".

Limits

• Up to 30 properties per event.
• Keys up to 300 characters, values up to 2,000 characters.
• Values must be strings, numbers or booleans — objects and arrays are rejected.

Never send personal data such as names, email addresses or user IDs as property values.

Choose which properties are shown

In Site settings → Custom properties you can add the properties you want to use. The list suggests keys your site has sent in the last 30 days, and you can add them all at once. Once the list has entries, only those properties are stored with new events — anything else is dropped. While the list is empty, all properties are kept.

The url and path properties used by outbound link, file download and form tracking are always kept.

View properties

Open the Properties tab at the bottom of the dashboard and choose a property to see visitors, events and percentage for each value. Click a value to filter the dashboard. Properties are also available as event:props:<name> in the Stats API.