Developer Toolbar

The Unleash Developer Toolbar lets you override feature flag values and context properties at runtime without making server changes. It’s designed for local development and testing workflows where you need to quickly test different flag configurations or context values.

Key features

• Flag overrides: Force boolean flags on or off, or select specific variant values
• Context overrides: Modify userId, sessionId, and custom properties to test targeting rules
• Persistence: Choose between memory, session, or local storage for your overrides
• Framework support: Works with React, Next.js, Vue, Angular, and JavaScript
• SSR support: Cookie-based state sync for server-side rendering in Next.js

Installation

Choose the installation command for your framework:

$
npm install @unleash/toolbar unleash-proxy-client

Import the CSS file to load the toolbar styles:

1
import '@unleash/toolbar/toolbar.css';

Quickstart

1
import { initUnleashToolbar } from '@unleash/toolbar';
2
import { UnleashClient } from 'unleash-proxy-client';
3
import '@unleash/toolbar/toolbar.css';
4
5
const client = initUnleashToolbar(new UnleashClient({
6
  url: 'https://your-unleash.com/api/frontend',
7
  clientKey: 'your-frontend-token',
8
  appName: 'my-app'
9
}), {
10
  storageMode: 'local',
11
  position: 'bottom-right'
12
});
13
14
await client.start();
15
16
// Use the wrapped client for flag checks
17
const isEnabled = client.isEnabled('my-feature');
18
const variant = client.getVariant('my-experiment');
19
20
// Listen for changes from toolbar or SDK updates
21
client.on('update', () => {
22
  const newValue = client.isEnabled('my-feature');
23
  updateUI(newValue);
24
});

Configuration options

Storage modes explained

• local (recommended for development): Persists across all tabs and browser restarts. Set overrides once, test everywhere.
• session: Persists within the current tab only. Useful for testing different configurations in multiple tabs simultaneously.
• memory: No persistence. Clears on every page reload. Use for quick one-off tests.

API reference

Access the toolbar instance via window.unleashToolbar:

1
const toolbar = window.unleashToolbar;
2
3
// Show/hide the toolbar panel
4
toolbar.show();
5
toolbar.hide();
6
7
// Get current state
8
const state = toolbar.getState();
9
10
// Set flag overrides
11
toolbar.setFlagOverride('my-feature', { type: 'flag', value: true });
12
toolbar.setFlagOverride('my-variant', { type: 'variant', variantKey: 'variant-b' });
13
toolbar.setFlagOverride('my-feature', null); // Clear override
14
15
// Set context overrides
16
toolbar.setContextOverride({
17
  userId: 'test-user-123',
18
  properties: { tier: 'premium' }
19
});
20
21
// Reset all overrides
22
toolbar.resetOverrides();
23
toolbar.resetContextOverrides();
24
25
// Clean up
26
toolbar.destroy();

Next.js server utilities

1
import { 
2
  applyToolbarOverrides, 
3
  applyToolbarOverridesToToggles, 
4
  getToolbarStateFromCookies 
5
} from '@unleash/toolbar/next/server';
6
7
// Apply overrides to definitions before evaluation (recommended)
8
const modifiedDefinitions = applyToolbarOverrides(definitions, cookieStore);
9
10
// Apply overrides to toggles after evaluation (alternative)
11
const modifiedToggles = applyToolbarOverridesToToggles(toggles, cookieStore);
12
13
// Read toolbar state directly from cookies
14
const state = getToolbarStateFromCookies(cookieStore);

Bundle size

The toolbar is optimized for minimal impact:

Requirements

• Browser: ES2020 support (Chrome 90+, Firefox 88+, Safari 14+)
• SDK versions:
  • unleash-proxy-client ^3.0.0
  • @unleash/proxy-client-react ^5.0.0 (optional)
  • @unleash/nextjs ^1.0.0 (optional)

Troubleshooting

1
import '@unleash/toolbar/toolbar.css';