Configuration

Hop configuration

Configuring Hop is a pretty straight-forward process. The only thing you need to do is to call the setup function from the Lua API:

require'hop'.setup {
  -- Hop configuration goes there
}

The possible configuration options are explained in a user-friendly way in this page. If you want to get an exhaustive list with default values of the all the configuration options without a guided tour, feel free to use:

:h hop-config

Note: some configuration options, like current_line_only or multi_windows do not really make sense when configured globally in setup. It is recommended to set them by overriding Lua calls instead. Indeed, everything that you put in setup can be passed to Lua invocations command, overriding what’s in setup. See the rest of the wiki for further information.

Ensuring your configuration is sound

At any time, if you are experiencing issues with Hop, you can check its health with the following command:

:checkhealth hop

Setting up your keys

The keys configuration option is one of the most important, if not the most. It’s a string that must contain unique characters. Characters showing up first (i.e. left-most) will be used first when creating labels for the hints to jump to. That option is important because Hop highly depends on your keyboard layout. The goal is to type characters that are close to your home row and limiting wrist movements. The default option is set for QWERTY. If you are using something else, it is highly recommended that you customize keys to yield the best experience possible.

For instance, for people using the bépo keyboard layout, keys can be set to:

require'hop'.setup {
  keys = 'etovxqpdygfblzhckisuran',
}

Configure the quit_key

That option allows you to change the key that you must type while Hop is active to abort / quit it. It defaults to <ESC>, which is a sane default for most people.

require'hop'.setup {
  quit_key = '<SPC>',
}

Jumping on sole occurrence with jump_on_sole_occurrence

Sometimes, you will trigger a Hop command that will only hint a single item. In such a case, the default behavior is to automatically jump to it. You can control that behavier with jump_on_sole_occurrence:

require'hop'.setup {
  jump_on_sole_occurrence = false,
}

Case insensitivity with case_insensitive

When using commands such as HopChar* or HopPattern, the default is be case insensitive: searching for a will hint both a and A.

Case insensitivity respects smartcase. So if you have set smartcase to true, abc will be fully case insensitive, while Abc will be case sensitive.

You can go case sensitive with the following:

require'hop'.setup {
  case_insensitive = false,
}

Control highlight autocommands with create_hl_autocmd

By default, Hop will inject its own highlighting. This is a default option that is sound for most people but can be annoying at some time (you want to write the highlights yourself, or you are using a theme plugin that resets them).

You can prevent Hop from automatically inserting the autocommands for highlighting with:

require'hop'.setup {
  create_hl_autocmd = false,
}

Change the display of the labels with uppercase_labels

Labels are displayed by printing the content of your keys. You can switch to upper case if you want with:

require'hop'.setup {
  uppercase_labels = true,
}

Current line only mode with current_line_only

This configuration option is probably not to be set in setup but by using the Lua API. By default, Hop actions will take place for the whole visible part of the buffer, unless modified by variations. current_line_only is a kind of variation that will scope Hop to the same line as the the one the cursor is on.

You can switch all Hop actions to current line only with the following:

require'hop'.setup {
  current_line_only = true,
}

Jump across windows with multi_windows

By default, Hop works in the buffer attached to the currently selected windows. You can make Hop hint every buffer in every visible windows in your terminal with the following setting:

require'hop'.setup {
  multi_windows = true,
}

Change the jump position with hint_position

When Hop hints items in a buffer, it actually hints two things: the beginning and the end of the target. That is especially true for HopPattern and HopWord. Of course, some Hop commands will have both their beginning and end overlapping, like HopChar1, HopLine and HopLineStart, for instance.

By default, Hop will jump to the beginning part of the jump target. You can switch to the end with:

require'hop'.setup {
  hint_position = require'hop.hint'.HintPosition.END,
}

Even more exotic: jump to the middle!

require'hop'.setup {
  hint_position = require'hop.hint'.HintPosition.MIDDLE,
}

Offset the jump with hint_offset

A very powerful feature: by default, Hop will jump to the target position. However, you can offset that position with hint_offset. That is especially useful to reimplement motions such as t / T, which move the cursor right before the actual thing you asked for. In that case, you would use hint_offset = -1.

If you want to always jump after the jump target, you can for instance use this:

require'hop'.setup {
  hint_offset = 1,
}

It is highly discouraged to set hint_offset in setup though. Have a look at the rest of the wiki to reimplement t / T or other kind of interesting motions.