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
• Movable and dismissible: Drag the floating icon to any window edge, minimize it to the icon, or hide it entirely until the next page refresh
• Custom banner: Show an optional message (with an optional link) to clarify the toolbar’s scope for your team

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.

Moving and hiding the toolbar

• Move it: Drag the floating icon to any window edge. It snaps to the nearest edge and remembers its position across reloads. Set draggable: false to disable dragging and keep the configured position.
• Minimize it: Click the minimize (_) button in the panel header to collapse the panel back to the floating icon.
• Hide it completely: Click the close (×) button to hide both the panel and the icon. This is temporary; the toolbar reappears (minimized) after a page refresh.

Adding a banner

Use the banner option to display a message in the toolbar, for example to clarify which flags the toolbar can override. Optionally add a link with bannerLink (and customize its label with bannerLinkText).

1
initUnleashToolbar(client, {
2
  banner: 'Only client-side flags are overridable here. Backend-only flags are unaffected.',
3
  bannerLink: 'https://docs.getunleash.io/integrate/toolbar',
4
  bannerLinkText: 'Learn more', // defaults to "Read more"
5
});

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';