JavaScript & TypeScript · v0.2.2
Vimweb documentation
Let visitors follow a link, press a button, or focus a field by typing its on-screen label. Vimweb runs in the browser and has zero runtime dependencies.
Quick start
Install the package in your website project.
npm install @mhariri/vimweb
Import the automatic entry once in your browser bundle.
import "@mhariri/vimweb/auto";
Open Keyboard shortcuts and check Enable vimWeb if needed. Dismiss the guide with Esc, then press f. Type the letters next to a link to follow it.
Try the same sequence here using the Shortcuts button at the top of this page, or open the interactive demo.
Installation
Automatic setup
The @mhariri/vimweb/auto entry uses your launcher or adds a Keyboard shortcuts button at the end of the page. It remembers each visitor’s choice in local storage when available and keeps open tabs on the same origin in sync.
Put this button in your header or near the top of the page so visitors see it when the page loads. Vimweb reveals it when ready.
<button type="button" data-vim-nav-launcher hidden>
Keyboard shortcuts
</button>
Enable shortcuts by default
The automatic entry starts shortcuts off for visitors with no saved preference. To start them enabled, set this attribute on your opening <html> tag. A visitor’s saved choice takes precedence.
<html lang="en" data-vim-nav-default-enabled="true">
Plain HTML
After installing the package, copy its JavaScript modules and license into a directory your site serves. Keep the modules together so their relative imports resolve.
mkdir -p assets/vimweb
cp node_modules/@mhariri/vimweb/*.js node_modules/@mhariri/vimweb/LICENSE assets/vimweb/
Load the entry with a module script. This example assumes the page sits alongside the assets directory.
<script type="module" src="./assets/vimweb/auto.js"></script>
You can also download the package archive, unpack it, and copy its JavaScript files and license into the same directory.
Optional Vimweb badge
Put this launcher in your header or near the top of the page so visitors see it when the page loads. It opens the guide even when shortcuts are off.
<button type="button" class="vimweb-badge" data-vim-nav-launcher hidden>
Try Vim in this website.
</button>
Import the stylesheet alongside the automatic entry in your browser bundle.
import "@mhariri/vimweb/badge.css";
For plain HTML, copy badge.css and badge.webp from the package's assets/ directory into the same directory as auto.js, then load the stylesheet in your page's head.
<link rel="stylesheet" href="./assets/vimweb/badge.css">
Override .vimweb-badge in your site's stylesheet to match your design. Try the badge in the interactive demo.
Keyboard commands
| Key | Action |
|---|---|
| f | Label visible links and controls. Type a full label to activate its target. |
| Backspace | Remove the last letter of a partially typed label. |
| Esc | Cancel hints or dismiss the guide. |
| j / k | Scroll down or up by 80 pixels. |
| g g | Jump to the top. Press lowercase g twice within 750 milliseconds. |
| G | Jump to the bottom. |
| ? | Open the guide and change your shortcut preference. |
Scroll commands act on the focused scrollable region, or on the page when focus is outside a scrollable region. A hint on a text field or select moves focus there so the visitor can type or choose an option.
Templates and colors
Choose the shape of your guide and hint labels independently from their colors. Set these attributes on <html> for either entry point.
<html lang="en" data-vim-nav-template="terminal"
data-vim-nav-palette="forest">
| Attribute | Values | Default |
|---|---|---|
data-vim-nav-template | classic has raised keycaps, minimal has flat keys and rounded labels, and terminal has a monospace guide and square labels. | classic |
data-vim-nav-palette | amber, ocean, forest | amber |
data-vim-nav-mode | auto, light, dark | auto |
Preview the templates and palettes with real hint labels and controls.
Follow a light or dark site theme
Leave the mode on auto. Vimweb follows the CSS color-scheme on html or body, or a <meta name="color-scheme"> declaration in the head. On a page without a declared scheme, it follows the visitor's system preference.
If your switch sets a class or data attribute, declare the scheme in the same CSS rule. The open guide, hint labels, and native form controls will follow the switch.
:root { color-scheme: light dark; }
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }
Customize individual colors
Set custom properties on html or body. The guide uses --vim-nav-surface, --vim-nav-text, --vim-nav-border, and --vim-nav-accent. Hints use --vim-nav-hint-bg and --vim-nav-hint-text. Set text and background colors together to keep labels readable.
:root {
--vim-nav-hint-bg: light-dark(#18304e, #cfe7ff);
--vim-nav-hint-text: light-dark(white, #102439);
}
Use --vim-nav-color-scheme: light or dark to choose a scheme just for Vimweb while its mode is auto.
Change appearance from JavaScript
A controller's appearance options override the corresponding HTML attributes. Update just the fields you want to change, including while a visitor is typing a hint. Set a field to undefined to use its HTML value or default again.
import { createVimNav } from "@mhariri/vimweb";
const nav = createVimNav({
appearance: { template: "minimal", palette: "ocean" }
});
nav.setAppearance({ mode: "dark" });
nav.setAppearance({ mode: undefined });
App integration
Choose the core entry, @mhariri/vimweb, when your app owns the settings UI or page lifecycle. The import is side-effect free. Create one controller per document, in the browser, once the body exists. Use either core setup or automatic setup for that document.
Mount and unmount a controller
This example wires an existing settings button to the guide. The app keeps its own ? binding and gives its editor full control of the keyboard.
import { createVimNav } from "@mhariri/vimweb";
export function mountKeyboardSettings(button) {
const nav = createVimNav({
enabled: false,
disabledKeys: ["?"],
exclude: ".code-editor"
});
button.addEventListener("click", nav.showHelp);
return () => {
button.removeEventListener("click", nav.showHelp);
nav.destroy();
};
}
Call the returned function when unmounting the page. To save the preference in your own settings store, pass onEnabledChange and use the saved boolean as enabled on the next mount.
Accessibility and focus
The guide uses a native modal dialog and returns focus to the opening control on dismissal. Scroll commands honor the visitor's reduced-motion preference.
Give components their own keys
Text fields, editable content, dialogs, and focused widgets such as comboboxes keep their keyboard interactions. Vimweb also yields during text composition and modifier shortcuts. To claim a key in another component, call event.preventDefault() before the event bubbles to the document.
Reserve commands globally with disabledKeys, or mark a whole region with data-vim-nav-ignore so Vimweb skips its targets and leaves its focused controls alone.
<section data-vim-nav-ignore aria-label="Code editor">
<textarea aria-label="Source code"></textarea>
</section>
Web components and frames
Hints reach visible controls in the document, open shadow roots, and slots. For a closed shadow root, expose the action on a focusable host. Give controls accessible names and use native links, buttons, and form fields where possible.
A same-origin iframe can have a controller of its own. After the frame loads, pass its contentDocument as the document option. Each frame owns its own installation and cleanup.
API reference
createVimNav(options?)
import { createVimNav } from "@mhariri/vimweb";
import type { VimNav, VimNavOptions, VimNavAppearance, VimNavKey }
from "@mhariri/vimweb";
The factory accepts VimNavOptions and returns a VimNav controller. All options are optional.
Options
enabled?: boolean- Initial shortcut state. Defaults to
truefor the core factory. The automatic entry uses the visitor’s saved choice or the site default. alphabet?: string- Letters used to build hint labels, in order. Supply at least two distinct lowercase ASCII letters with no duplicates. The default is
asdfghjklqwertyuiopzxcvbnm. disabledKeys?: readonly VimNavKey[]- Commands reserved by your page. Defaults to an empty array. A
VimNavKeyis one of"f","j","k","gg","G", or"?". exclude?: string- A CSS selector for subtrees that own keyboard interaction, such as
".editor, .map". Targets in matching regions are also excluded from hints. document?: Document- The browser document to install into. Defaults to the current document.
onEnabledChange?: (enabled: boolean) => void- Called with the new state when the guide or app enables or disables shortcuts.
appearance?: VimNavAppearance- Optional
template,palette, andmodefields. Each uses the corresponding appearance choices and defaults.
Controller members
readonly enabled: boolean- The current shortcut state.
enable(): void- Enable shortcuts for the document.
disable(): void- Disable shortcuts and dismiss active hints. The settings guide stays available.
showHints(): void- Open hints from a toolbar or command palette. It respects the shortcut state, a reserved f command, current focus, and modal dialogs.
showHelp(): void- Open the shortcut guide and its enable checkbox, including when shortcuts are off.
setAppearance(patch: VimNavAppearance): void- Update selected appearance fields in place. An open guide keeps its focus and an active hint keeps the letters already entered.
destroy(): void- Remove listeners, hints, and the guide, and release the document so another controller can be installed.