Open-source project
brookhong/Surfingkeys avatar
brookhong/Surfingkeys

Surfingkeys: Keyboard Control of the Browser, Configured in JavaScript

Map your keys for web surfing, expand your browser with javascript and keyboard.

6,203 stars573 forksJavaScriptMIT

At a glance

What is it?
Surfingkeys is a Chrome, Firefox, Edge and Safari extension that maps keystrokes to JavaScript functions for navigation and page control. Its selling point is that every mapping is code you can edit, and its cost is that every mapping is code you have to maintain.
Who is it for?
Adopt Surfingkeys if you already think in Vim motions and want mappings that call your own JavaScript, and if you accept that the configuration is a script you maintain rather than a settings dialog. Skip it if you need the same feature set on every browser, since the README's availability table marks Omnibar as partial on Safari and PDF viewer and proxy as Chromium only.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • brookhong/Surfingkeys6,203 ★ · +28
Star history
Repository2026-09-232026-11-15
brookhong/Surfingkeys6.2k6.2k

28 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Surfingkeys replaces, and for whom

The extension takes the keyboard model of the VIM editor and applies it to a browser tab. The README is explicit that this is not only for VIM users: it says Surfingkeys is for anyone who needs more shortcuts for their own functions. That second half is the real audience. If you only wanted j and k to scroll, a dozen extensions do that. Surfingkeys is aimed at people who want to bind a key to a function they wrote, and it exposes that through an api object available in the settings script.

The README's own example is a mapping from Ctrl-y to a popup:

js
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).');
});

The second argument is a description string, and the README states that help messages are generated automatically for mappings. That matters more than it sounds: a keyboard layer with fifty bindings is unusable if you cannot list them, and here the list is produced from the same declarations that create the bindings. Press ? on any page to see it.

The default layer is broad. The README lists e and d for page up and down, f to follow links, v for visual mode, T to switch tabs, t to search bookmarks and history, / to find in the current page, and ;e to open the settings page. Scroll actions are documented as working on scrollable DIVs, not just the top window, and w switches frames when a page has any. None of that is unusual for this category of extension. What is unusual is that the same script that configures those defaults is the one you extend.

Three modes, and why visual mode is the interesting one

Surfingkeys runs in normal, visual and insert mode. Normal mode is the default when a page loads, and every mapping added with mapkey works there. Insert mode is what you would expect: typing into a field. Visual mode is where the design shows.

Pressing v toggles visual mode and draws an indicator at the bottom of the page reading Caret or Range, plus a large cursor on the page. The README explains the size choice directly: a normal cursor is sometimes hard to locate on a web page. Caret means jkhl moves the cursor; Range means the same keys extend a selection. Actions then apply to the selected text, and the README notes that * searches the word under the cursor in visual mode.

This is a different bet from extensions that treat the page as a flat list of clickable elements. Hint-based navigation, which Surfingkeys also has through f, assumes you want to jump to something already on screen. Visual mode assumes you want to compose an operation over text that may not be a link or a button at all. The cost is a second keyboard grammar to learn on top of the first.

Installing Surfingkeys and opening the settings page

Installation is through the store listing for your browser, not from the repository. The README points to the Chrome Web Store for Google Chrome and Chromium-based browsers, Firefox Add-ons, Microsoft Edge Addons, and the Mac App Store for Safari. The Safari build works on macOS and iOS, with the caveat that iOS requires an external keyboard, except for one feature the README calls Search selected with.

After installing, open any site and press ? or u to see the default mappings. Esc hides the popover. Then try the defaults before writing anything:

bash
# in the browser, not the shell
e    # scroll page up
d    # scroll page down
;e   # open the settings page

;e is the entry point for everything custom. The README describes editing your own settings as a first-class part of the extension, and the settings are JavaScript. The same api.mapkey call shown earlier is what you write there. If you would rather keep the configuration in a file on disk, the README documents loading settings from a local file, and the availability table notes that on Chromium and Firefox this needs a native host, while on Safari it is macOS only.

One practical note from package.json: the project declares node >=22.14.0 in its engines field, and the build script runs clean, test, build:doc and build:prod in sequence through npm-run-all. That is the path for building the extension yourself from source, not for using it.

Where the browser limits the extension

The README does not claim the keyboard can reach everything. It says Surfingkeys does its best to make full use of the keyboard, then states that there are limitations from Google Chrome itself, and links to a separate write-up titled Brook Build of Chromium for a more thorough experience. That link is the honest boundary of this project: some of what a keyboard-first browser would need is not reachable from an extension, and the author's answer is a patched browser rather than a workaround.

The availability table carries the rest of the constraints. Omnibar is listed as Y for Chromium and Firefox but partly for Safari. Windows management and Tab Groups are N on Safari. PDF viewer and Proxy are Chromium only, Sync across devices is unavailable on Firefox, and Markdown preview is Chromium and Firefox but not Safari. Firefox above 57 and Safari above 15 are the stated minimums, with Chromium above 45.

Read that table as a product decision, not a defect list. A single codebase spanning four browser families will not have uniform capability, and publishing the matrix is more useful than pretending otherwise. But if your team is standardized on Safari, you are adopting a smaller product than the one described in the feature list, and the README says so before you install anything.

Surfingkeys against Vimium and Vimium C

The comparison people reach for is Vimium. The distinction that matters is where configuration lives. Vimium's model centers on a fixed set of Vim-like commands with options you toggle. Surfingkeys states its position in the first line of its feature list: all settings are set up within a javascript file, which makes it easy to create mappings to user-customized functions. The unit of configuration is a function, not a checkbox.

That difference cuts both ways. A mapping like the Ctrl-y popup above has no equivalent in a command-list extension, because the behavior is arbitrary code. The same property means your configuration is a program: it can break, it can depend on api methods that change, and it is yours to debug.

Tridactyl is another common comparison. It is a Firefox-focused project, while Surfingkeys ships for Chromium, Firefox, Edge and Safari from one repository. If Firefox is your only target, that breadth buys you nothing.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-10-29. The version in package.json is 1.19.3. The repository has no published GitHub releases, so there is nothing here to say about what changed in that version or what a migration between versions involves.

The licence is MIT, declared both in the repository and in package.json. MIT permits use, modification and redistribution with the licence and copyright notice preserved. This is not legal advice; if you are bundling the extension into a product, read the LICENSE file rather than this paragraph.

The upgrade cost is the part worth thinking about before adopting. Store-installed extensions update on the browser's schedule, and your settings script runs against whatever api surface the installed version exposes. The README documents the api through generated documentation (the build:doc script runs the documentation tool over api.js and related source files into docs/api.md), which means the api reference is derived from source and moves with it. A mapping that calls an api method is a dependency on that method.

Editorial conclusion

Adopt Surfingkeys if you already think in Vim motions and want mappings that call your own JavaScript, and if you accept that the configuration is a script you maintain rather than a settings dialog. Skip it if you need the same feature set on every browser, since the README's availability table marks Omnibar as partial on Safari and PDF viewer and proxy as Chromium only. Before rolling it out, verify two things on your own machine: that the native host required for loading settings from a local file is set up if you want file-based configuration, and that the mappings you rely on behave in the sites you use daily.

Frequently asked questions

What are the main differences between Surfingkeys and Vimium?

Surfingkeys is configured entirely in JavaScript, so any keystroke can be mapped to a function you define with api.mapkey. Vimium's model, as implied by the comparison, centers on a fixed command set rather than user-written functions.

How do you use Surfingkeys?

Install it from the store listing for your browser, open a site, and press ? or u to see the default mappings. Press ;e to open the settings page where your own JavaScript mappings live. Esc hides the help popover.

Is Surfingkeys safe?

What is documented is that the source is public under the MIT licence, and that loading settings from a local file on Chromium and Firefox requires a native host.

Surfingkeys vs Vimium on Reddit?

The documented difference is that Surfingkeys settings are JavaScript mappings created with api.mapkey, while Vimium's model centers on a fixed command set.

Official sources

  1. brookhong/Surfingkeys on GitHub
  2. Issues
  3. License: MIT
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/brookhong-surfingkeys.svg)](https://hysenlabs.com/projects/brookhong-surfingkeys)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/brookhong-surfingkeys.svg)](https://hysenlabs.com/projects/brookhong-surfingkeys)

Was this useful?