leap.nvim

Leap is a general-purpose motion plugin for Neovim, building and improving primarily on vim-sneak, with the ultimate goal of establishing a new standard interface for moving around in the visible area in Vim-like modal editors. It allows you to reach any target in a very fast, uniform way, and minimizes the required focus level while executing a jump.

How to use it (TL;DR)

Leap's default motions allow you to jump to any position in the visible editor area by entering a 2-character search pattern, and then potentially a label character to pick your target from multiple matches, similar to Sneak. The main novel idea in Leap is that you get a preview of the target labels - you can see which key you will need to press before you actually need to do that.

• Initiate the search in the forward (s) or backward (S) direction, or in the other windows (gs). (Note: you can use a single key for the current window or even the whole tab page, if you are okay with the trade-offs.)
• Start typing a 2-character pattern ({char1}{char2}).
• After typing the first character, you see "labels" appearing next to some of the {char1}{?} pairs. You cannot use the labels yet - they only get active after finishing the pattern.
• Enter {char2}. If the pair was not labeled, then voilà, you're already there. You can safely ignore the remaining labels, and continue editing - those are guaranteed non-conflicting letters, disappearing on the next keypress.
• Else: type the label character, that is now active. If there are more matches than available labels, you can switch between groups, using <space> and <backspace>.

Character pairs give you full coverage of the screen:

• s{char}<space> jumps to the last character on a line.
• s<space><space> jumps to actual end-of-line characters, including empty lines.

At any stage, <enter> consistently jumps to the next available target (<backspace> steps back):

• s<enter>... repeats the previous search.
• s{char}<enter>... can be used as a multiline substitute for fFtT motions.

Why is this method cool?

It is ridiculously fast: not counting the trigger key, leaping to literally anywhere on the screen rarely takes more than 3 keystrokes in total, that can be typed in one go. Often 2 is enough.

At the same time, it reduces mental effort to almost zero:

• You don't have to weigh alternatives: a single universal motion type can be used in all non-trivial situations.

• You don't have to compose in your head: one command achieves one logical movement.

• You don't have to be aware of the context: the eyes can keep focusing on the target the whole time.

• You don't have to make decisions on the fly: the sequence you should enter is determined from the very beginning.

• You don't have to pause in the middle: if typing at a moderate speed, at each step you already know what the immediate next keypress should be, and your mind can process the rest in the background.

Getting started

Status

The plugin is not 100% stable yet, but don't let that stop you - the usage basics are extremely unlikely to change. To follow breaking changes, subscribe to the corresponding issue.

Requirements

• Neovim >= 0.7.0 stable, or latest nightly

Dependencies

• repeat.vim, for dot-repeats (.) to work

Installation

Use your preferred method or plugin manager. No extra steps needed besides defining keybindings - to use the default ones, put the following into your config (overrides s, S and gs in all modes):

require('leap').create_default_mappings() (init.lua)

lua require('leap').create_default_mappings() (init.vim)

Extras

Experimental features, APIs might be subject to change.

Next steps

Help files are not exactly page-turners, but I suggest at least skimming :help leap, even if you don't have a specific question yet (if nothing else: :h leap-usage, :h leap-config, :h leap-events). While Leap has deeply thought-through, opinionated defaults, its small(ish) but comprehensive API makes it pretty flexible.

Design considerations in detail

The ideal

Premise: jumping from point A to B on the screen should not be some exciting puzzle, for which you should train yourself; it should be a non-issue. An ideal keyboard-driven interface would impose almost no more cognitive burden than using a mouse, without the constant context-switching required by the latter.

That is, you do not want to think about

• the command: we need one fundamental targeting method that can bring you anywhere: a jetpack on the back, instead of airline routes (↔ EasyMotion and its derivatives)
• the context: it should be enough to look at the target, and nothing else (↔ vanilla Vim motion combinations using relative line numbers and/or repeats)
• the steps: the motion should be atomic (↔ Vim motion combos), and ideally you should be able to type the whole sequence in one go, on more or less autopilot (↔ any kind of "just-in-time" labeling method; note that the "search command on steroids" approach by Pounce and Flash, where the labels appear at an unknown time by design, makes this last goal impossible)

All the while using as few keystrokes as possible, and getting distracted by as little incidental visual noise as possible.

How do we measure up?

It is obviously impossible to achieve all of the above at the same time, without some trade-offs at least; but in our opinion Leap comes pretty close, occupying a sweet spot in the design space. (The worst remaining offender might be visual noise, but clever filtering in the preview phase can help - see :h leap.opts.preview_filter.)

The one-step shift between perception and action is the big idea that cuts the Gordian knot: a fixed pattern length combined with previewing labels can eliminate the surprise factor from the search-based method (which is the only viable approach - see "jetpack" above). Fortunately, a 2-character pattern - the shortest one with which we can play this trick - is also long enough to sufficiently narrow down the matches in the vast majority of cases.

Fixed pattern length also makes (safe) automatic jump to the first target possible. You cannot improve on jumping directly, just like how f and t works, not having to read a label at all, and not having to accept the match with <enter> either. However, we can do this in a smart way: if there are many targets (more than 15-20), we stay put, so we can use a bigger, "unsafe" label set - getting the best of both worlds. The non-determinism we're introducing is less of an issue here, since the outcome is known in advance.

In sum, compared to other methods based on labeling targets, Leap's approach is unique in that it

• offers a smoother experience, by (somewhat) eliminating the pause before typing the label

• feels natural to use for both distant and close targets

FAQ

Bugs

Defaults

Features

Configuration

Miscellaneous

Extending Leap

There are lots of ways you can extend the plugin and bend it to your will - see :h leap.leap() and :h leap-events. Besides tweaking the basic parameters of the function (search scope, jump offset, etc.), you can:

• give it a custom action to perform, instead of jumping
• feed it with custom targets, and only use it as labeler/selector
• customize its behavior on a per-call basis via autocommands

Some practical examples: