# 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.

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

**Usage Examples:**

```typescript
// 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

```typescript { .api }
/**
 * 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

```typescript { .api }
/**
 * User's intended use of the toolbar
 */
type ToolbarUserIntent =
    | 'add-action'
    | 'edit-action'
    | 'heatmaps'
    | 'flags'
    | 'experiments'
    | 'surveys';
```

### ToolbarSource

```typescript { .api }
/**
 * Source from which toolbar was loaded
 */
type ToolbarSource = 'url' | 'localstorage' | 'opt-in';
```

### ToolbarVersion

```typescript { .api }
/**
 * 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

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

### Via Configuration

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

## Common Use Cases

### Heatmap Viewing

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

### Feature Flag Testing

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

### Action Creation

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

### Experiment Management

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

## Best Practices

### Development vs Production

```typescript
// 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

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

### Conditional Loading

```typescript
// 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
