API.md

November 29, 2025 ยท View on GitHub

Table of Contents

mapkey

Create a shortcut in normal mode to execute your own action.

Parameters

  • keys string the key sequence for the shortcut.
  • annotation string a help message to describe the action, which will displayed in help opened by ?.
  • jscode function a Javascript function to be bound. If the function needs an argument, next pressed key will be fed to the function.
  • options object domain: regex, a Javascript regex pattern to identify the domains that this mapping works, for example, /github\.com/i says that this mapping works only for github.com, repeatIgnore: boolean, whether this action can be repeated by dot command. (optional, default null)

Examples

mapkey("<Space>", "pause/resume on youtube", function() {
    var btn = document.querySelector("button.ytp-ad-overlay-close-button") || document.querySelector("button.ytp-ad-skip-button") || document.querySelector('ytd-watch-flexy button.ytp-play-button');
    btn.click();
}, {domain: /youtube.com/i});

vmapkey

  • See: mapkey

Create a shortcut in visual mode to execute your own action.

Parameters

  • keys string the key sequence for the shortcut.
  • annotation string a help message to describe the action, which will displayed in help opened by ?.
  • jscode function a Javascript function to be bound. If the function needs an argument, next pressed key will be fed to the function.
  • options object domain: regex, a Javascript regex pattern to identify the domains that this mapping works, for example, /github\.com/i says that this mapping works only for github.com, repeatIgnore: boolean, whether this action can be repeated by dot command. (optional, default null)

imapkey

  • See: mapkey

Create a shortcut in insert mode to execute your own action.

Parameters

  • keys string the key sequence for the shortcut.
  • annotation string a help message to describe the action, which will displayed in help opened by ?.
  • jscode function a Javascript function to be bound. If the function needs an argument, next pressed key will be fed to the function.
  • options object domain: regex, a Javascript regex pattern to identify the domains that this mapping works, for example, /github\.com/i says that this mapping works only for github.com, repeatIgnore: boolean, whether this action can be repeated by dot command. (optional, default null)

map

Map a key sequence to another in normal mode.

Parameters

  • new_keystroke string a key sequence to replace
  • old_keystroke string a key sequence to be replaced
  • domain regex a Javascript regex pattern to identify the domains that this mapping works. (optional, default null)
  • new_annotation string use it instead of the annotation from old_keystroke if provided. (optional, default null)

Examples

map(';d', '<Ctrl-Alt-d>');

unmap

Unmap a key sequence in normal mode.

Parameters

  • keystroke string a key sequence to be removed.
  • domain regex a Javascript regex pattern to identify the domains that this mapping will be removed. (optional, default null)

Examples

unmap("<<", /youtube.com/);

unmapAllExcept

Unmap all keybindings except those specified.

Parameters

  • keystrokes array the keybindings you want to keep.
  • domain regex a Javascript regex pattern to identify the domains that this mapping will be removed. (optional, default null)

Examples

unmapAllExcept(['E','R','T'], /google.com|twitter.com/);

imap

  • See: map

Map a key sequence to another in insert mode.

Parameters

  • new_keystroke string a key sequence to replace
  • old_keystroke string a key sequence to be replaced
  • domain regex a Javascript regex pattern to identify the domains that this mapping works. (optional, default null)
  • new_annotation string use it instead of the annotation from old_keystroke if provided. (optional, default null)

iunmap

  • See: unmap

Unmap a key sequence in insert mode.

Parameters

  • keystroke string a key sequence to be removed.
  • domain regex a Javascript regex pattern to identify the domains that this mapping will be removed. (optional, default null)

cmap

  • See: map

Map a key sequence to another in omnibar.

Parameters

  • new_keystroke string a key sequence to replace
  • old_keystroke string a key sequence to be replaced
  • domain regex a Javascript regex pattern to identify the domains that this mapping works. (optional, default null)
  • new_annotation string use it instead of the annotation from old_keystroke if provided. (optional, default null)

vmap

  • See: map

Map a key sequence to another in visual mode.

Parameters

  • new_keystroke string a key sequence to replace
  • old_keystroke string a key sequence to be replaced
  • domain regex a Javascript regex pattern to identify the domains that this mapping works. (optional, default null)
  • new_annotation string use it instead of the annotation from old_keystroke if provided. (optional, default null)

vunmap

  • See: unmap

Unmap a key sequence in visual mode.

Parameters

  • keystroke string a key sequence to be removed.
  • domain regex a Javascript regex pattern to identify the domains that this mapping will be removed. (optional, default null)

lmap

  • See: map

Map a key sequence to another in lurk mode.

Parameters

  • new_keystroke string a key sequence to replace
  • old_keystroke string a key sequence to be replaced
  • domain regex a Javascript regex pattern to identify the domains that this mapping works. (optional, default null)
  • new_annotation string use it instead of the annotation from old_keystroke if provided. (optional, default null)

addSearchAlias

Add a search engine alias into Omnibar.

Parameters

  • alias string the key to trigger this search engine, one or several chars, used as search alias, when you input the string and press space in omnibar, the search engine will be triggered.
  • prompt string a caption to be placed in front of the omnibar.
  • search_url string the URL of the search engine, for example, https://www.s.com/search.html?query=, if there are extra parameters for the search engine, you can use it as https://www.s.com/search.html?query={0}&type=cs or https://www.s.com/search.html?type=cs&query=(since order of URL parameters usually does not matter).
  • search_leader_key string <search_leader_key><alias> in normal mode will search selected text with this search engine directly without opening the omnibar, for example sd. (optional, default s)
  • suggestion_url string the URL to fetch suggestions in omnibar when this search engine is triggered. (optional, default null)
  • callback_to_parse_suggestion function a function to parse the response from suggestion_url and return a list of strings as suggestions. Receives two arguments: response, the first argument, is an object containing a property text which holds the text of the response; and request, the second argument, is an object containing the properties query which is the text of the query and url which is the formatted URL for the request. (optional, default null)
  • only_this_site_key string <search_leader_key><only_this_site_key><alias> in normal mode will search selected text within current site with this search engine directly without opening the omnibar, for example sod. (optional, default o)
  • options object favicon_url URL for favicon for this search engine, skipMaps if true disable creating key mappings for this search engine (optional, default null)

Examples

addSearchAlias('d', 'duckduckgo', 'https://duckduckgo.com/?q=', 's', 'https://duckduckgo.com/ac/?q=', function(response) {
    var res = JSON.parse(response.text);
    return res.map(function(r){
        return r.phrase;
    });
});

removeSearchAlias

Remove a search engine alias from Omnibar.

Parameters

  • alias string the alias of the search engine to be removed.
  • search_leader_key string <search_leader_key><alias> in normal mode will search selected text with this search engine directly without opening the omnibar, for example sd. (optional, default s)
  • only_this_site_key string <search_leader_key><only_this_site_key><alias> in normal mode will search selected text within current site with this search engine directly without opening the omnibar, for example sod. (optional, default o)

Examples

removeSearchAlias('d');

searchSelectedWith

Search selected with.

Parameters

  • se string a search engine's search URL
  • onlyThisSite boolean whether to search only within current site, need support from the provided search engine. (optional, default false)
  • interactive boolean whether to search in interactive mode, in case that you need some small modification on the selected content. (optional, default false)
  • alias string only used with interactive mode, in such case the url from se is ignored, SurfingKeys will construct search URL from the alias registered by addSearchAlias. (optional, default "")

Examples

searchSelectedWith('https://translate.google.com/?hl=en#auto/en/');

Clipboard.read

Read from clipboard.

Parameters

  • onReady function a callback function to handle text read from clipboard.

Examples

Clipboard.read(function(response) {
  console.log(response.data);
});

Clipboard.write

Write text to clipboard.

Parameters

  • text string the text to be written to clipboard.

Examples

Clipboard.write(window.location.href);

Hints.setNumeric

Use digits as hint label, with it set you could type text to filter links, this API is to replace original setting like Hints.numericHints = true;.

Examples

Hints.setNumeric();

Hints.setCharacters

Set characters for generating hints, this API is to replace original setting like Hints.characters = "asdgqwertzxcvb";.

Parameters

  • characters string the characters for generating hints.

Examples

Hints.setCharacters("asdgqwertzxcvb");

Hints.dispatchMouseClick

  • See: Hints.create

The default onHintKey implementation.

Parameters

  • element HTMLElement the element for which the pressed hint is targeted.

Examples

mapkey('q', 'click on images', function() {
    Hints.create("div.media_box img", Hints.dispatchMouseClick);
}, {domain: /weibo.com/i});

Hints.click

Click element or create hints for elements to click.

Parameters

  • links string or array of HTMLElement, click on it if there is only one in the array or force parameter is true, otherwise hints will be generated for them. If links is a string, it will be used as css selector for getClickableElements.
  • force boolean force to click the first input element whether there are more than one elements in links or not. (optional, default false)

Examples

mapkey('zz', 'Hide replies', function() {
    Hints.click(document.querySelectorAll("#less-replies:not([hidden])"), true);
});

Hints.create

  • See: Hints.dispatchMouseClick

Create hints for elements to click.

Parameters

  • cssSelector string or array of HTMLElement, if links is a string, it will be used as css selector.
  • onHintKey function a callback function on hint keys pressed.
  • attrs object active: whether to activate the new tab when a link is opened, tabbed: whether to open a link in a new tab, multipleHits: whether to stay in hints mode after one hint is triggered. (optional, default null)

Examples

mapkey('yA', '#7Copy a link URL to the clipboard', function() {
    Hints.create('*[href]', function(element) {
        Clipboard.write('[' + element.innerText + '](' + element.href + ')');
    });
});

Returns Promise which will be resolved how many hints are created.

Hints.style

Set styles for hints.

Parameters

  • css string styles for hints.
  • mode string sub mode for hints, use text for hints mode to enter visual mode. (optional, default null)

Examples

Hints.style('border: solid 3px #552a48; color:#efe1eb; background: none; background-color: #552a48;');
Hints.style("div{border: solid 3px #707070; color:#efe1eb; background: none; background-color: #707070;} div.begin{color:red;}", "text");

Normal.passThrough

Enter PassThrough mode.

Parameters

  • timeout number? how many milliseconds to linger in PassThrough mode, to ignore it will stay in PassThrough mode until an Escape key is pressed.

Normal.scroll

Scroll within current target.

Parameters

  • type string down | up | pageDown | fullPageDown | pageUp | fullPageUp | top | bottom | left | right | leftmost | rightmost | byRatio

Normal.feedkeys

Feed keys into Normal mode.

Parameters

  • keys string the keys to be fed into Normal mode.

Normal.jumpVIMark

Jump to a vim-like mark.

Parameters

  • mark string a vim-like mark.

Visual.style

Set styles for visual mode.

Parameters

  • element string element in visual mode, which can be marks and cursor.
  • style string css style

Examples

Visual.style('marks', 'background-color: #89a1e2;');
Visual.style('cursor', 'background-color: #9065b7;');

Front.showEditor

Launch the vim editor.

Parameters

  • element HTMLElement the target element which the vim editor is launched for, this parameter can also be a string, which will be used as default content in vim editor.
  • onWrite function a callback function to be executed on written back from vim editor.
  • type string the type for the vim editor, which can be url, if not provided, it will be tag name of the target element. (optional, default null)
  • useNeovim boolean the vim editor will be the embeded JS implementation, if useNeovim is true, neovim will be used through natvie messaging. (optional, default false)

Examples

mapkey(';U', '#4Edit current URL with vim editor, and reload', function() {
    Front.showEditor(window.location.href, function(data) {
        window.location.href = data;
    }, 'url');
});

Front.openOmnibar

Open the omnibar.

Parameters

  • args object type the sub type for the omnibar, which can be Bookmarks, AddBookmark, History, URLs, RecentlyClosed, TabURLs, Tabs, Windows, VIMarks, SearchEngine, Commands, OmniQuery and UserURLs.

Examples

mapkey('ou', '#8Open AWS services', function() {
    var services = Array.from(top.document.querySelectorAll('#awsc-services-container li[data-service-href]')).map(function(li) {
        return {
            title: li.querySelector("span.service-label").textContent,
            url: li.getAttribute('data-service-href')
        };
    });
    if (services.length === 0) {
        services = Array.from(top.document.querySelectorAll('div[data-testid="awsc-nav-service-list"] li[data-testid]>a')).map(function(a) {
            return {
                title: a.innerText,
                url: a.href
            };
        });
    }
    Front.openOmnibar({type: "UserURLs", extra: services});
}, {domain: /console.amazonaws|console.aws.amazon.com/i});

Front.registerInlineQuery

Register an inline query.

Parameters

  • args object url: string or function, the dictionary service url or a function to return the dictionary service url, parseResult: function, a function to parse result from dictionary service and return a HTML string to render explanation, headers: object[optional], in case your dictionary service needs authentication.

RUNTIME

Call background action with args, the callback will be executed with response from background.

Parameters

  • action string a background action to be called.
  • args object the parameters to be passed to the background action.
  • callback function a function to be executed with the result from the background action.

Examples

RUNTIME('getTabs', {queryInfo: {currentWindow: true}}, response => {
  console.log(response);
});

aceVimMap

Map the key sequence lhs to rhs for mode ctx in ACE editor.

Parameters

  • lhs string a key sequence to replace
  • rhs string a key sequence to be replaced
  • ctx string a mode such as insert, normal.

Examples

aceVimMap('J', ':bn', 'normal');

addVimMapKey

Add map key in ACE editor.

Parameters

Examples

addVimMapKey(
    {
        keys: 'n',
        type: 'motion',
        motion: 'moveByCharacters',
        motionArgs: {
            forward: false
        }
    },

    {
        keys: 'e',
        type: 'motion',
        motion: 'moveByLines',
        motionArgs: {
            forward: true,
            linewise: true
        }
    }
);

getBrowserName

Get current browser name

Returns string "Chrome" | "Firefox" | "Safari"

Front.showBanner

Show message in banner.

Parameters

  • msg string the message to be displayed in banner.
  • timeout number milliseconds after which the banner will disappear. (optional, default 1600)

Examples

Front.showBanner(window.location.href);

Front.showPopup

Show message in popup.

Parameters

  • msg string the message to be displayed in popup.

Examples

Front.showPopup(window.location.href);

isElementPartiallyInViewport

Check whether an element is in viewport.

Parameters

  • el Element the element to be checked.
  • ignoreSize boolean whether to ignore size of the element, otherwise the element must be with size 4*4. (optional, default false)

Returns boolean

getLargeElements

Get large elements that are currently visible in the viewport. A large element is defined as one that takes up a significant portion of the viewport.

Parameters

  • minWidth number Minimum width as a fraction of viewport width (0.0 to 1.0) (optional, default 0.3)
  • minHeight number Minimum height as a fraction of viewport height (0.0 to 1.0) (optional, default 0.3)

Examples

// Get elements that are at least 30% of viewport dimensions
var largeElements = getLargeElements();

// Get elements that are at least 50% of viewport dimensions
var veryLargeElements = getLargeElements(0.5, 0.5);

Returns Array<Element> Array of large visible elements

getClickableElements

Get all clickable elements. SurfingKeys has its own logic to identify clickable elements, such as a HTMLAnchorElement or elements with cursor as pointer. This function provides two parameters to identify those clickable elements that SurfingKeys failed to identify.

Parameters

  • selectorString string extra css selector of those clickable elements.
  • pattern regex a regular expression that matches text of the clickable elements.

Examples

var elms = getClickableElements("[rel=link]", /click this/);

Returns array array of clickable elements.

Open links in new tabs.

Parameters

  • str string links to be opened, the links should be split by \n if there are more than one.
  • simultaneousness number how many tabs will be opened simultaneously, the rest will be queued and opened later whenever a tab is closed. (optional, default 5)

Examples

tabOpenLink('https://github.com/brookhong/Surfingkeys')