Creating surveys

Last updated:

|Edit this page

To create a new survey, go to the surveys tab in the PostHog app, and click on the "New survey" button in the top right. This presents you with a collection of survey templates or you can click "Create blank survey" in the top right to create your own.

Survey templates

After choosing one, you are brought to a form where you can complete the details of your new survey:

Create a survey

Here's a breakdown of each field in the form:

Presentation

There are three options for displaying a survey:

  1. Popover: Use PostHog's prebuilt user interfaces to show surveys as a popover in the bottom corner of the screen.

  2. API: Implement your own survey UI and use PostHog to handle display logic, capturing results, and analytics.

Steps

Steps is where you set up your question(s), label, choice(s), description, button text, and confirmation message. You must subscribe to surveys to add multiple questions.

You can also add conditional logic to display certain questions.

Tip: The description supports HTML, so you can do things like add images with an <img> tag.

PostHog supports multiple question types which are all available for both popover and API display modes.

TypePreview
Freeform textOpen text survey
Link/NotificationLink survey
Rating emojiEmoji rating survey
Rating - numberNumber rating survey
Single choice selectSingle choice select survey
Multiple choice selectMultiple choice survey

Customization

Customization enables you to change the look, feel, and timing of your popover survey:

  • The color of the background, border, and buttons.
  • The position of the popover at the bottom of the screen.
  • The placeholder text.
  • The visibility of the PostHog branding.
  • Whether to shuffle the order of the choices and questions.
  • The delay (in seconds) before the survey appears on the page.
  • Whether the confirmation message auto disappears after 5 seconds.
Delay survey customization

Display conditions

This specifies the conditions a user must meet to be shown the survey. A user must meet ALL the conditions to be eligible.

You can display your survey to specific users based on:

  • Linked feature flag: Whether a user has a specific feature flag enabled. For example, if you're rolling out a new landing page using a feature flag new-landing-page, you can gather feedback only from users who have that flag enabled. This is also a way to show surveys to cohorts (but it must be a non-behavioral one).

  • URL targeting: Show when URL either contains a string, exactly matches a string, matches a regex.

  • Selector matches: Whether a specific element exists or appears on the page with the specified class name or ID. For example, you can display a survey with #my-button or .my-button selector. This is useful for showing a survey after a user action.

  • Wait period: Hide surveys from users who have seen a survey in the last X days. Note that a user who completes a survey are never shown the same survey again, even if no wait period is set.

  • Person and group properties: If you are capturing identified events, you can display a survey to users who have specific person or group properties. For example, you can target a survey to users who have a property is_paying=true. This also includes a percentage rollout option.

  • User sends events: Display a survey to users who have sent a specific event during their session.

Display conditions

Completion conditions

This enables you to stop your survey once you receive a specific number of responses. Note that because it takes time for PostHog to process responses, this is a rough guideline. Your survey might receive slightly more responses than you set.

Repeating surveys

By default, surveys are shown once to each user until they either dismiss it or complete it. After that, they won't see the survey again.

You can also configure surveys to repeat at specific intervals, which is useful for gathering feedback from users on a regular basis.

Repeating surveys

For example, you can configure settings like:

  • Repeat this survey 3 times, once every 30 days: The survey will be shown to a user up to 3 times total, with a 30-day gap between each showing.
DateEventExplanation
Jan 1Survey shown and completedFirst showing of the survey. User completes it, starting the 30-day timer
Jan 2-30No survey shownWithin 30-day waiting period after first completion
Jan 31Survey becomes eligible30 days have passed since first completion
Feb 15Survey shown and completedUser visits site and completes survey for the second time
Feb 16-Mar 16No survey shownWithin 30-day waiting period after second completion
Mar 17Survey becomes eligible30 days have passed since second completion
Apr 1Survey shown and completedUser completes survey for the third and final time
After Apr 1Survey never shown again for this userMaximum number of repetitions (3) reached

A survey is considered "shown" when a user either completes or dismisses it. The repeat interval timer starts from that moment. For example, if you set a survey to repeat every 90 days and a user completes it on January 1st, they won't see it again until April 1st, regardless of how many times they visit your site in between.

Note: Users must still match any display conditions you've set each time the survey becomes eligible to show again.

Launching your survey

Once you've set up your survey, click "Save as draft" to save your survey. This enables you to review any changes before launching. Then, when you're ready to launch, click the "Launch" button.

If you've created a popover survey, your survey will begin showing immediately to users matching your display conditions.

If you've created an API survey, you'll need to add your custom survey code before launching.

Questions? Ask Max AI.

It's easier than reading through 562 docs articles.

Community questions

Was this page useful?

Next article

Implementing custom surveys

At its most basic level, a survey is a collection of response events. If you wanted to, you could capture events from anywhere, like in this example of a hardcoded Next.js feedback survey: The benefit of using PostHog beyond this is that it handles: Survey content. Customize question type, text, and more. Change it at runtime without needing to redeploy your app. Display conditions. This means not showing the same survey multiple times, the wrong survey, or a survey that has collected enough…

Read next article