Surfingkeys: Vim-Style Keyboard Navigation for Chrome, Firefox and Safari

What Surfingkeys Does and Who It Is For

Surfingkeys is for anyone who wants to navigate, interact with and control their browser primarily from the keyboard. The README describes it as created "in the spirit of the VIM editor" but notes it is not only for VIM users. The core premise is that mouse-driven browsing is slow for power users and that keyboard mappings should be programmable, not fixed.

The practical users are developers, writers and researchers who keep many tabs open, navigate reference material frequently, and find moving a hand to the mouse for every link or tab switch a constant friction. The extension ships default mappings for common operations and allows any keystroke to call arbitrary JavaScript, which makes it extensible without requiring the author to anticipate every use case.

JavaScript Configuration and the Mapping API

The key design choice that distinguishes Surfingkeys from most keyboard extension alternatives is that all settings are defined in JavaScript. The README shows an example:

api.mapkey('<Ctrl-y>', 'Show me the money', function() {
    api.Front.showPopup('a well-known phrase uttered by characters in the 1996 film Jerry Maguire (Escape to close).');
});

This means users can call any browser API or web service from a keypress. The `api.mapkey` function registers a binding in normal mode; `vmapkey` registers bindings in visual mode. Help messages are generated automatically from the description string passed to `mapkey`, so a keypress of `?` or `u` shows a searchable overlay of all active bindings.

Settings can be loaded from a local file (using a native host on Chrome and Firefox, or directly on macOS with Safari), which allows version-controlling and syncing the configuration across machines. The `package.json` shows the project is at version 1.19.2 and requires Node.js 22.14.0 or above for building.

Installing Surfingkeys and Getting Started

Installation is from the official extension stores. For Chrome and Chromium-based browsers, the extension is at the Chrome Web Store. For Firefox, it is available from the Firefox Add-ons site. For Edge, it is at the Microsoft Edge Addons store. For Safari on macOS and iOS, it is available from the Mac App Store.

After installation, open any page and press `?` or `u` to see the default mappings overlay. A few core defaults to try first:

- Press `e` to scroll a page up. - Press `d` to scroll a page down. - Press `f` to enter Hints mode and follow a link by keyboard. - Press `T` to switch tabs. - Press `t` to search bookmarks and history. - Press `/` to find text in the current page.

Hints mode is one of the most-used features. Pressing `f` overlays letter labels on every clickable element; typing the label activates that element. Continuous following uses `cf` instead.

On iOS via Safari, the README notes that an external keyboard must be connected because the iOS keyboard does not expose key events the same way. One exception exists: the "Search selected with" feature is available on iOS without an external keyboard.

Surfingkeys Modes and Visual Selection

Surfingkeys operates in three modes: normal, visual and insert. Normal mode is active by default when a page loads. Visual mode is entered with `v` and provides a large, visible text cursor for selecting content. The large cursor is a deliberate choice: the README notes that a standard cursor is difficult to locate on a busy page.

In visual mode, the cursor starts in Caret state (moving without selecting). Pressing `v` again switches to Range state (selecting as you move). Standard Vim movement keys apply: `j`, `k`, `h`, `l`, `b`, `w`, `0`, `$` move the cursor. Pressing `sg` with text selected searches Google with the selection. The `*` key searches for the word under the cursor.

The dot key `.` repeats the previous action, matching a common Vim pattern. The `zz` key centers the window on the cursor. These bindings apply in visual mode and normal mode respectively, maintaining consistency with VIM conventions where they carry over.

Feature Availability Across Browsers

Not all features work in all browsers. The README provides a detailed capability matrix. Follow links, all Surfingkeys modes, visual mode, Vim-like marks, tab switching, commands and smooth scroll work in Chromium, Firefox and Safari. Windows management is missing from Safari. PDF viewer is Chromium-only. Device sync is available on Chromium and Safari but not Firefox. Proxy settings are Chromium-only. Markdown preview is available on Chromium and Firefox but not Safari. Tab Groups work on Chromium and Firefox but not Safari.

This matters in practice: Firefox users who rely on proxy configuration through Surfingkeys will not find that feature available. Safari users who want to load settings from a local file can do so on macOS but the README indicates this requires a native host on Chrome and Firefox.

The README also mentions a "Brook Build of Chromium" for users who want deeper keyboard integration beyond what the standard Chrome extension API permits.

Surfingkeys Versus Vimium: Where They Differ

Vimium is the most direct alternative. Both extensions provide Vim-style navigation for Chrome and Firefox, both implement hints for link following, and both support normal and visual modes. The practical difference is in configuration: Vimium uses a simple text-based mapping format, while Surfingkeys uses full JavaScript.

For users who just want to remap a handful of keys, Vimium's format is faster to learn. For users who want to call browser APIs, fetch external data, or chain operations in a custom function, Surfingkeys' JavaScript model is necessary. Surfingkeys also includes session management, a built-in Vim editor and Emacs editor for text input fields, a PDF viewer on Chromium, and LLM chat integration, which are not part of Vimium's feature set.

The trade-off is complexity: a JavaScript settings file requires knowing JavaScript, and debugging a misbehaving binding means reading JavaScript rather than checking a config line.

Licence, Maintenance and Build Details

Surfingkeys is released under the MIT licence, which permits use in any project without copyleft obligations. The last push to the repository was on 2026-09-21, and the project does not publish formal GitHub releases; the current version is tracked in package.json as 1.19.2.

The build uses webpack; `npm run build:prod` produces the production extension bundle and documentation. Tests run with Jest. The project requires Node.js 22.14.0 as a minimum for development. The repository includes a CONTRIBUTING.md and a GitHub Actions workflow for Node CI.

For users who encounter limitations from Chrome's extension API boundary, the README points to the Brook Build of Chromium as an option for a more complete experience, though that requires installing a custom Chromium build.

Editorial conclusion

Surfingkeys is the right choice for anyone who wants deep keyboard control of the browser and is comfortable writing a few lines of JavaScript to customize it. The JavaScript configuration model separates it clearly from Vimium, which uses a simpler text format. Firefox users should verify the specific features they need against the browser capability table, as proxy, PDF viewer and device sync are not available on Firefox. Safari support on iOS requires an external keyboard. The extension is MIT-licensed and available from the official browser stores for Chrome, Firefox, Edge and Safari.

Frequently asked questions

Official sources

1. brookhong/Surfingkeys on GitHub
2. Issues
3. License: MIT
4. Project website
5. README