DelayTrain

Train yourself to stop repeating keys... gently

How does it work? • Installation • Configuration • Commands • Contributing

"Stop using arrow keys!" "Stop using hjkl!"

If you're familiar with the (neo)vim community you've probably heard this a million times. The whole point of vim is to seamlessly navigate where you need to go without constantly repeating keypresses. Why press j ten times when you can press 10j, or }, or search.

But if you've been using vim for a while this may be a harder habit to break. You try to stop relying on this type of navigation but you only catch yourself after the fact. You might chastize yourself and move on but the habit stays there.

Most recommendations involve disabling these keys altogether, but this only increases frustration. Sometimes your next position is directly above and the quickest option is to press k. This might help in the long run but it's incredibly annoying and hard to stick with.

That's where DelayTrain comes in.

DelayTrain will still let you use these keybindings, but it only punishes you when you keep hitting them. If you need to navigate directly below, you can still do that. But if you need to navigate 5 lines below using repeated keypresses, DelayTrain will gently remind you that there might be a better way by stopping the keypress from working for a certain amount of time.

And DelayTrain doesn't just work for hjkl. Mappings are included to prevent repeated arrow key presses and you can configure delaytrain to prevent anything else like w or b.

How does it work?

DelayTrain takes two configurable values, delay_ms and grace_period.

When you first hit a configured keypress (like j), the delay_ms timer starts. You are given a grace_period of repeated keypresses within the delay_ms timer before the key stops working. Once the delay_ms timer ends, everything is reset.

Examples

We'll use a few tables to show how this works. Assume the follwing:

• delay_ms = 1000
• grace_period = 2

By default the grace_period is 1, but setting it to 2 allows you to press the key twice before it stops working.

Keypress	Time	Grace Period	Does it work?
j	0ms	1	Yes
j	200ms	2	Yes
j	500ms	3	No
j	1000ms	1	Yes

Each keypress starts a dedicated delay_ms timer and has a dedicated grace_period. So if you're trying to navigate down and to the left, this still works.

Keypress	Time	Grace Period	Does it work?
j	0ms	1	Yes
j	200ms	2	Yes
h	500ms	1	Yes
j	700ms	3	No
h	1000ms	2	Yes
j	1200ms	1	Yes
h	1400ms	3	No
h	1500ms	1	Yes

Installation

Install with vim-plug:

Plug 'ja-ford/delaytrain.nvim'

or with packer:

  -- Delay repeat execution of certain keys
  use 'ja-ford/delaytrain.nvim'

For the default setup (see defaults below), you can simply place the following into your init.lua:

require('delaytrain').setup()

Configuration

You can configure all DelayTrain settings through the setup() function. The default DelayTrain mappings are included below:

    require('delaytrain').setup {
        delay_ms = 1000,  -- How long repeated usage of a key should be prevented
        grace_period = 1, -- How many repeated keypresses are allowed
        keys = {          -- Which keys (in which modes) should be delayed
            ['nv'] = {'h', 'j', 'k', 'l'},
            ['nvi'] = {'<Left>', '<Down>', '<Up>', '<Right>'},
        },
    }

Mappings

The keys option allows you to delay different keypresses in different modes. This takes the following KV pair:

    ['list_of_applicable_modes'] = {'keys', 'you', 'want', 'delayed'},

Modes can be added based on their short-names (ex: normal is 'n', insert is 'i') and multiple modes can be added to a single keymap.

This option ties into a call to vim.keymap.set(), so mode short-names and key names should match what is possible in that function.

Options

Global options can be modified to change delay/grace period settings on the fly:

• g:delaytrain_delay_ms
• g:delaytrain_grace_period

Commands

The following commands allow you to turn DelayTrain on and off without calling setup() again:

• :DelayTrainEnable
• :DelayTrainDisable
• :DelayTrainToggle

By default, DelayTrain is turned on when the setup() function is called.

Contributing

This has been tested on my personal and work machines using nvim-nightly and Neovide. This is a REALLY SMALL plugin so while there shouldn't be a lot of issues it's entirely possible I missed something. I'm also brand new to plugin development so if you notice anything off please feel free to open up an issue or send me a PR!