Toolbar

Note: The PostHog toolbar is only available for the JavaScript web SDK.

The toolbar is like "Inspect Element" for PostHog features and data.

When enabled, the toolbar appears as an overlay on your product or website – it's not visible to your users.

With it, you can interact with elements to create actions, visualize heatmaps, override feature flags, and more.

How to launch the toolbar

1. In your PostHog instance, go to Launch Toolbar in the left-hand menu
2. Add the URLs you wish to enable the toolbar for. Only you will be able to see it – not your users.
3. Click Save and then Launch.
4. A new window will open with toolbar on your website. Click on the toolbar to interact with it.

Creating actions using the toolbar

The toolbar enables you to easily create actions by clicking elements directly on your website.

To do this, click on the 🔍 Inspect button on the toolbar. This will add a blue overlay to your website. Then, if you click on an element, you will be shown the option to create an action from it.

You can also create a more advanced action using the following additional options:

1. Add another element

If you want your action to cover more than one element, you can click Add another element right above Create Action.

This is an OR operation, meaning that the action will be recorded if either Element A or Element B are clicked.

This is useful if you have various buttons that take you to the same page, for instance, and only care that the user clicks one of them. A common use case for this is leveraging the action as a funnel step.

2. Element filters

These are used by PostHog to find the specific element you're creating the action for.

• Link target: Where a click on the element leads to (if available).

• Text: Inner text of the element (if available).

• Page URL: If you have the same element at the same position in various pages (e.g. navbar elements), the default action will capture them all. To prevent this, you can set an exact URL or specify a pattern for pages where this exact action should be recorded.

• Selector: Path to the element on the page. If you're not happy with the selector PostHog is using automatically, you could, for example, select elements based on their id or data-attr. You can type a selector into the "Selector" field in the action creation modal to do this.

Or in the same modal, click Edit the selector to use our element picker to build the selector you want.

Viewing your existing actions

You can view your existing actions on your page by clicking the Actions button on the Toolbar. This highlights elements associated with an action and is a useful way to check that elements are associated correctly.

By clicking on a specific element, you can update or delete the action.

The number in the green box on the top left of the element is the action's index in your list of actions (and does not represent how many times that action was triggered).

The number in the yellow box next to the "Actions" button in the toolbar represents the total number of actions you have created.

Override feature flags using the toolbar

The toolbar enables you to test your feature flags.

You can enable, disable, or override your feature flags, and then view how your website or app changes with the new feature flags values.

To do this, click on the Feature Flags button in the toolbar, search for any feature flag, and click on the toggles to change its value.

This will only affect your browser, not other users or your flags evaluated on the backend. You may also need to refresh the page to see how your change affect your website.

Troubleshooting and FAQ

Toolbar not loading or displaying

When launched, the toolbar injects an API token in the format #__posthog=JSON in your site's URL, like this: http://mysite.com/#__posthog=JSON.

The toolbar won't load if you have a frontend that overrides the injected API token (the information after the #) before the posthog-js library (or snippet) loads and has a chance to read the API token.

To solve this, retrieve the __posthog JSON from the URL before it is overridden and call posthog.loadToolbar(JSON) in your code:

const toolbarJSON = new URLSearchParams(window.location.hash.substring(1)).get('__posthog')
if (toolbarJSON) {
    posthog.loadToolbar(JSON.parse(toolbarJSON))
}

Toolbar authentication issue (with reverse proxy)

If you are having issues authenticating your toolbar and are using a reverse proxy, be sure to pass the proper ui_host config parameter when initializing (like ui_host: 'https://us.posthog.com'). This ensures PostHog makes the authentication request to the correct host.

Toolbar not working with Nuxt

The PostHog toolbar currently doesn't work for Nuxt users because Nuxt overrides the URL of our static asset URL from https://app-static-prod.posthog.com to https:/app-static-prod.posthog.com, removing the second /. If you have a solution, please let us know.

Toolbar non-functional on Wordpress website

Some Wordpress plugins, notably WPCodebox, rewrite the CSS of our toolbar. If you're running PostHog on a Wordpress website and run into issues with formatting in the toolbar, it's possible a plugin is to blame.

Toolbar disppearing on transition with Astro

Astro with view transitions enabled can cause the toolbar to disappear on transition. To prevent this, you can:

1. Retrieve the __posthog JSON from the URL on astro:page-load.
2. Prevent the toolbar from loading on astro:before-swap.
3. Load the toolbar from JSON on astro:after-swap.

<script>
    document.addEventListener('astro:page-load', () => {
        if (!window.posthog) {
            // Initialize PostHog here...
        }
        var toolbarJSON = new URLSearchParams(window.location.hash.substring(1)).get('__posthog');
        if (toolbarJSON) {
            window.toolbarJSON = toolbarJSON;
        }
    }, { once: true });

    document.addEventListener('astro:before-swap', ev => {
        window._postHogToolbarLoaded = false;
    });

    document.addEventListener('astro:after-swap', () => {
        if (window.toolbarJSON) {
            window.posthog.loadToolbar(JSON.parse(window.toolbarJSON));
        }
    });
</script>