or run

tessl search

tessl/npm-posthog-js

tessl install tessl/npm-posthog-js@1.335.0

PostHog Browser JS Library is a comprehensive browser analytics and feature management SDK that enables developers to capture user events, track product analytics, manage feature flags, record session replays, and implement feedback mechanisms like surveys and conversations in web applications.

Toolbar

The PostHog toolbar is an overlay interface that provides debugging, feature flag testing, heatmap viewing, and other development tools directly in your application. It's useful for development, QA testing, and debugging production issues.

Capabilities

Load Toolbar

Loads and displays the PostHog toolbar overlay on the current page.

/**
 * Loads the PostHog toolbar
 * @param params - Toolbar configuration parameters
 * @returns True if toolbar loaded successfully, false otherwise
 */
function loadToolbar(params: ToolbarParams): boolean;

Usage Examples:

// Load toolbar with default settings
posthog.loadToolbar({});

// Load toolbar with specific user intent
posthog.loadToolbar({
    userIntent: 'heatmaps'
});

// Load toolbar with API key
posthog.loadToolbar({
    apiURL: 'https://us.i.posthog.com',
    temporaryToken: 'temp-token-123'
});

Types

ToolbarParams

/**
 * Parameters for loading the toolbar
 */
interface ToolbarParams {
    /**
     * API URL for the toolbar
     * @default Current api_host from config
     */
    apiURL?: string;

    /**
     * Temporary authentication token
     */
    temporaryToken?: string;

    /**
     * Action ID to jump to
     */
    actionId?: string | number;

    /**
     * User intent for toolbar usage
     */
    userIntent?: ToolbarUserIntent;

    /**
     * Toolbar source
     */
    source?: ToolbarSource;

    /**
     * Toolbar version
     */
    toolbarVersion?: ToolbarVersion;

    /**
     * Data attributes to use for element selection
     * @default ['data-attr']
     */
    dataAttributes?: string[];

    /**
     * Whether to use JS for selecting elements
     * @default false
     */
    jsURL?: boolean;
}

ToolbarUserIntent

/**
 * User's intended use of the toolbar
 */
type ToolbarUserIntent =
    | 'add-action'
    | 'edit-action'
    | 'heatmaps'
    | 'flags'
    | 'experiments'
    | 'surveys';

ToolbarSource

/**
 * Source from which toolbar was loaded
 */
type ToolbarSource = 'url' | 'localstorage' | 'opt-in';

ToolbarVersion

/**
 * Version of toolbar to load
 */
type ToolbarVersion = 'toolbar' | '2' | '3';

Enabling the Toolbar

Via URL Parameter

Add __posthog parameter to your URL:

https://yourapp.com?__posthog=true

This will prompt for authentication and load the toolbar.

Programmatically

// Load toolbar programmatically
posthog.loadToolbar({
    userIntent: 'heatmaps'
});

Via Configuration

// Disable toolbar metrics (reduces overhead)
posthog.init('<your-project-api-key>', {
    advanced_disable_toolbar_metrics: true
});

Common Use Cases

Heatmap Viewing

// Load toolbar for heatmap analysis
function viewHeatmaps() {
    posthog.loadToolbar({
        userIntent: 'heatmaps'
    });
}

Feature Flag Testing

// Load toolbar to test feature flags
function testFeatureFlags() {
    posthog.loadToolbar({
        userIntent: 'flags'
    });
}

Action Creation

// Load toolbar to create actions
function createAction() {
    posthog.loadToolbar({
        userIntent: 'add-action'
    });
}

Experiment Management

// Load toolbar for experiment viewing
function manageExperiments() {
    posthog.loadToolbar({
        userIntent: 'experiments'
    });
}

Best Practices

Development vs Production

// Only load toolbar in non-production environments
if (process.env.NODE_ENV !== 'production') {
    // Enable toolbar via URL or local storage
    posthog.init('<your-project-api-key>', {
        advanced_disable_toolbar_metrics: false
    });
} else {
    // Disable toolbar in production
    posthog.init('<your-project-api-key>', {
        advanced_disable_toolbar_metrics: true
    });
}

Custom Data Attributes

// Use custom data attributes for element selection
posthog.loadToolbar({
    dataAttributes: ['data-test-id', 'data-analytics', 'data-attr']
});

Conditional Loading

// Load toolbar based on user role
const userRole = getCurrentUserRole();

if (userRole === 'admin' || userRole === 'developer') {
    posthog.loadToolbar({
        userIntent: 'heatmaps'
    });
}

Security Considerations

The toolbar requires authentication and should only be accessible to authorized users
Use temporary tokens for toolbar access in production environments
Consider disabling toolbar in production or restricting access by IP/user role
Toolbar metrics can add overhead - disable them in production with advanced_disable_toolbar_metrics: true

Keyboard Shortcuts

When the toolbar is loaded, these keyboard shortcuts are available:

Escape: Close/minimize toolbar
?: Show help and shortcuts
H: Toggle heatmaps (when viewing heatmaps)

Notes

The toolbar is loaded asynchronously and may take a moment to appear
Toolbar state persists in localStorage between page loads
The toolbar requires network connectivity to load and function
Toolbar features depend on your PostHog plan and configuration

Version