Module follow

Link hinting for luakit

Link hints allow interacting with web pages without the use of a mouse. When follow mode is entered, all clickable elements are highlighted and labeled with a short number. Typing either an element number or part of the element text will "follow" that hint, issuing a mouse click. This is most commonly used to click links without using the mouse and focus text input boxes. In addition, the ex-follow mode offers several variations on this behavior. For example, instead of clicking, the URI of a followed link can be copied into the clipboard. Another example would be hinting all images on the page, and opening the followed image in a new tab.

Customizing hint labels

If you prefer to use letters instead of numbers for hint labels (useful if you use a non-qwerty keyboard layout), this can be done by replacing the label_maker function:

local select = require "select"

select.label_maker = function (s)
    local chars = s.charset("asdfqwerzxcv")
    return s.trim(s.sort(s.reverse(chars)))

Here, the charset() function generates hints using the specified letters. For a full explanation of what the trim(sort(reverse(...))) construction does, see the select module documentation; the short explanation is that it makes hints as short as possible, saving you typing.

Note: this requires modifying the select module because the actual link hinting interface is implemented in the select module; the follow module provides the follow and ex-follow user interface on top of that.

Hinting with non-latin letters

If you use a keyboard layout with non-latin keys, you may prefer to use non-latin letters to hint. For example, using the Cyrillic alphabet, the above code could be changed to the following:

local chars = s.charset("ФЫВАПРОЛДЖЭ")

Hint text direction

Hints consisting entirely of characters which are drawn Left-to-Right (eg Latin, Cyrillic) or characters drawn Right-to-Left (eg Arabic, Hebrew), will render intuitively in the appropriate direction. Hints will be drawn non-intuitively if they contain a mix of Left-to-Right and Right-to-Left characters.

Punctuation characters do not have an intrinsic direction, and will be drawn using the direction specified by the HTML/CSS context in which they appear. This leads to corner cases if the hint charset contains punctuation characters, for example:

local chars = s.charset("fjdksla;ghutnvir")

In this case, hints will display intuitively if used on pages which are drawn Left-to-Right, but not on pages drawn Right-to-Left.

To guard against this, it is recommended that if punctuation characters are used in hints, a clause should be added to a user stylesheet giving an explicit text direction eg:

#luakit_select_overlay .hint_label { direction: ltr; }

Alternating between left- and right-handed letters

To make link hints easier to type, you may prefer to have them alternate between letters on the left and right side of your keyboard. This is easy to do with the interleave() label composer function.

local chars = s.interleave("qwertasdfgzxcvb", "yuiophjklnm")

Matching only hint labels, not element text

If you prefer not to match element text, and wish to select hints only by their label, this can be done by specifying the pattern_maker:

-- Match only hint label text
follow.pattern_maker = follow.pattern_styles.match_label

Ignoring element text case

To ignore element text case when filtering hints, set the following option:

-- Uncomment if you want to ignore case when matching
follow.ignore_case = true



Type: number
Duration to ignore keypresses after following a hint. 200ms by default.

After each follow ignore all keys pressed by the user to prevent the accidental activation of other key bindings.


Type: string
CSS applied to the follow mode overlay.


Type: {[string]=function}
Table of functions used to select a hint matching style.


Type: function
Hint matching style functions.


Type: boolean
Whether text case should be ignored in follow mode. True by default.


Type: {[string]=string}
Element selectors used to filter elements to follow.


Type: {[string]=table}
Site specific element selectors used to extend selectors. Table keys should be website domains. Values are tables with the same structure as selectors.