Add the OpenKeyNav Toolbar
The .openKeyNav-toolBar host gives users persistent, state-aware reminders for activating OpenKeyNav, opening its Shortcut Guide, and leaving the current mode. OpenKeyNav supplies and updates the compact toolbar while the application chooses its location.
Try the live toolbar
The keeper's collection
OpenKeyNav Toolbar
The live component, presented like a prized possession. Its inscription changes as the command layer and its modes move through different states.
Live toolbar. Use the command shown above and watch the toolbar reveal its next state.
See the base component
The same live .openKeyNav-toolBar without custom styling:
This second live instance is hidden from assistive technology to prevent duplicate announcements.
OpenKeyNav updates the command content. Place and style the host for your application.
Place the toolbar in an application
The current compact toolbar works in a navigation bar, sidebar, or settings block. Choose a predictable location with enough room for the Shortcut Guide to expand.
- OpenKeyNav
- Populates the toolbar and updates its built-in contextual guidance as the command layer and modes change state.
- You
- Place and style the host, provide the complete command reference, and verify the displayed guidance against every configured state.
ResultUsers receive contextual command reminders and a verified route to the complete keyboard instructions.
Add one toolbar host
Place one empty element with the exact, case-sensitive openKeyNav-toolBar class in a stable part of the page or application navigation:
<aside aria-label="OpenKeyNav keyboard commands">
<div class="openKeyNav-toolBar"></div>
</aside>
Initialize OpenKeyNav normally:
const openKeyNav = new OpenKeyNav();
openKeyNav.init();
init() populates matching hosts already in the document. A body-level observer also initializes a host inserted later with the class already present, which supports client-rendered routes and components. In a server-rendered application, initialize OpenKeyNav on the client after hydration.
OpenKeyNav replaces the host's contents whenever its state changes. Keep fallback guidance and the application's complete command reference outside the host. When the application removes OpenKeyNav, it also owns removal of the host element.
The generated keycaps are informational rather than controls. Provide a native button when the application offers a clickable on/off control, expose its state with aria-pressed, and synchronize it with keyboard changes and the user's restored preference.
Style the toolbar for its setting
The .openKeyNav-toolBar host is ready for application styling. OpenKeyNav owns the changing content; the application owns the host's placement and presentation. Scope overrides through an application wrapper so they do not affect other OpenKeyNav surfaces:
.toolbarDisplay .openKeyNav-toolBar {
color: #fffdf7 !important;
background: #17373a !important;
border-color: #f4c95d;
border-radius: 0.75rem;
}
.toolbarDisplay .openKeyNav-toolBar .keyButton {
color: #2e250e;
background: #fff2ae;
border-color: #9c7130;
}
The color declarations use !important because the current component applies its configured foreground and background colors inline. The current generated markup also exposes .keyButton, .keyButtonLabel, and .openKeyNav-toolBar-expanded for scoped presentation. Test custom styles across every toolbar state, zoom level, supported viewport, and translated command label.
Follow the current state
With the default configuration, the toolbar presents this contextual guidance:
| OpenKeyNav state | Toolbar content |
|---|---|
| Command layer off | openKeyNav and Shift+O to turn it on |
| Command layer on, no active mode | Shortcuts and O to open the Shortcut Guide |
| Shortcut Guide open | Escape to close, Click with K, and Drag with M when Move Mode is configured |
| Click Mode | Click Mode and Escape to leave |
| Move Mode | Drag Mode and Escape to leave |
| Structural Navigation active | Structural Navigation and Alt+R to leave |
The current toolbar uses Drag and Drag Mode for the workflow documented elsewhere as Move Mode. Include that displayed wording when writing application-specific instructions.
The toolbar reads keys.modifierKey and keys.menu for activation, keys.click and keys.move for the Shortcut Guide, and keys.structuralNavigation for its Structural Navigation hint. Supply key configuration before init() and test the rendered toolbar after customization. Click Mode and Move Mode exit text is fixed to Escape; the Structural Navigation exit hint is fixed to Alt plus the structural-navigation key.
See keys for the primary mode bindings.
Provide the complete command set
Pair the compact toolbar with a static, accessible reference containing every command the application enables and tests. Include heading and heading-level navigation, scroll navigation, reverse commands, Structural Navigation movement, the alternate Q exit, editable-field overrides, and any application-specific bindings.
Tell users that OpenKeyNav is available, how to turn it on and off, and how to leave each configured mode. Advertise Move Mode after configuring and testing its sources, destinations, completion behavior, feedback, and focus outcome.
The Quick Start Guide lists the primary commands, and the Structural Navigation guide documents that mode's complete command set.
Place and announce the toolbar accessibly
Use one primary toolbar in a predictable location. The labeled aside in the example creates a discoverable complementary landmark while allowing users to read updates on demand.
The OpenKeyNav homepage uses its primary toolbar as a polite status region:
<div
class="openKeyNav-toolBar"
role="status"
aria-live="polite"
aria-label="OpenKeyNav shortcut status"
></div>
When adopting this live-region pattern, expose one live toolbar and test it together with OpenKeyNav's notification alerts to prevent repeated announcements. When notifications are enabled, the keyboard on/off command and Click Mode or Move Mode transitions emit assertive alerts configured through notifications. A positive duration makes those alerts transient; a duration of 0 makes each alert persistent and dismissible. Structural Navigation presents its active context through a persistent polite status.
Use the toolbar for persistent contextual guidance, notification alerts for timely workflow feedback, and static instructions for the complete command set.
Fit the current compact layout
The current release supplies the compact toolbar layout. Give its Shortcut Guide room to expand below the host, and test ancestor overflow, zoom, narrow viewports, and translated text.
Place the compact toolbar inside an application-designed navigation bar, sidebar, or settings block today, with complete instructions alongside it when space permits. Dedicated sidebar and settings-block sizes are candidates for a later release.