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
• Keyboard support: Open and close the toolbar with a configurable shortcut, operate every control from the keyboard, and dismiss it with Esc
• Screen reader support: Landmark, tab, and radio group semantics, labeled controls, and visible focus indicators
• 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, or press Esc while focus is inside the panel, to collapse the panel back to the floating icon. Esc also returns focus to wherever you opened the panel from.
• 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
});

Keyboard and accessibility

The toolbar is fully operable from the keyboard.

Keyboard shortcuts

To open the toolbar panel, or move focus into it when it’s already open:

• Windows/Linux: Ctrl + Shift + F
• macOS: Cmd + Shift + F

Pressing the same shortcut again from inside the panel minimizes it.

Once the panel is open:

Use the shortcut option to rebind the shortcut if it conflicts with one in your app, or set it to false to register no global key listener:

1
initUnleashToolbar(client, {
2
  shortcut: 'mod+shift+u', // mod is Cmd on macOS, Ctrl elsewhere
3
});

Shortcut-driven setup

To render nothing until the toolbar is summoned, and open it with focus already in the flag search box:

1
initUnleashToolbar(client, {
2
  showToggleButton: false,
3
  focusOnOpen: 'search',
4
});

The toolbar stays mounted while closed. It’s hidden with display: none, so there’s no re-initialization cost when it reopens, and it stays out of both the tab order and the accessibility tree while hidden.

Focus behavior

The panel isn’t modal. The page underneath stays interactive, is never marked inert, and focus is never trapped, since watching your app react to a flag change is the point of the tool and keyboard users need to be able to get back out to it.

When you open the panel from the keyboard, focus lands on the panel itself rather than on a control, so screen readers announce the region and its name. The panel also draws a focus ring so that sighted keyboard users can see that focus has left the page. The ring stays off when the panel is opened by clicking the floating icon.

From there, focus is tethered to wherever you summoned the panel from:

• Tab off the last control, or Shift + Tab off the first, returns focus to the element you opened the panel from and leaves the panel open. The next Tab continues through your page from that point.
• The shortcut is the way back in. Pressed from the page while the panel is open, it pulls focus into the panel instead of closing it. Pressed from inside the panel, it minimizes.
• Esc minimizes and hands focus back to the same element, or to the floating icon if the icon is what opened the panel.

If there’s no element to return to, because the panel was opened by clicking the icon or the original element has been removed from the page, Tab follows the browser’s normal order.

Calling hide() from your own code only moves focus if the toolbar currently holds it, so hiding the toolbar programmatically never interrupts a user who is working in your app.

Screen reader support

• The panel is a labeled region landmark, so assistive technology can jump straight to it regardless of where the toolbar sits in the tab order.
• Tabs follow the WAI-ARIA tabs pattern, with arrow-key navigation and a single tab stop.
• Each flag’s off/default/on control is a radiogroup labeled with the flag name, so assistive technology reports which state is in effect. The group is a single tab stop, so you can move past a flag with one Tab press instead of three.
• Icon-only controls have visually hidden text labels rather than relying on tooltips.
• Animations are suppressed when the user prefers reduced motion.

Focus ring color

The keyboard focus ring follows themePreset automatically, and both presets meet the 3:1 contrast ratio that WCAG requires of non-text indicators. Controls on the colored header use a white ring instead, since primaryColor is already required to be dark enough for the header’s white text.

Set theme.focusColor only if a custom backgroundColor leaves the default ring hard to see, for example a dark background while staying on the light preset:

1
initUnleashToolbar(client, {
2
  theme: { backgroundColor: '#101010', textColor: '#f5f5f5', focusColor: '#A9A6F5' },
3
});

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
toolbar.toggle();
7
8
// Open with focus on a specific control
9
toolbar.show({ focus: 'search' });   // flag search box
10
toolbar.show({ focus: 'context' });  // first Context field, switching tabs
11
toolbar.show({ focus: 'panel' });    // the panel itself (default)
12
13
// Get current state
14
const state = toolbar.getState();
15
16
// Set flag overrides
17
toolbar.setFlagOverride('my-feature', { type: 'flag', value: true });
18
toolbar.setFlagOverride('my-variant', { type: 'variant', variantKey: 'variant-b' });
19
toolbar.setFlagOverride('my-feature', null); // Clear override
20
21
// Set context overrides
22
toolbar.setContextOverride({
23
  userId: 'test-user-123',
24
  properties: { tier: 'premium' }
25
});
26
27
// Reset all overrides
28
toolbar.resetOverrides();
29
toolbar.resetContextOverrides();
30
31
// Clean up
32
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:

Of the core bundle, only ~2.4 KB is the entry point. The panel UI (~9.6 KB) is a separate chunk loaded asynchronously, so it doesn’t block your initial bundle.

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