winmove.nvim

Easily move windows around

🚧 This plugin is under development 🚧

moving-around-windows.mov

• Requirements
• Installing
• Configuration
• Autocommands
• Public API
• Contributing
• FAQ
• Showcase
• Similar projects

Requirements

• Neovim 0.8.0+

Installing

• vim-plug

Plug 'MisanthropicBit/winmove.nvim'

• packer.nvim

use 'MisanthropicBit/winmove.nvim'

Configuration

If you are content with the defaults that are shown below, you don't need to call the configure function. No default keymaps are set other than those active during modes.

require('winmove').configure({
    highlights = {
        move = "Search", -- Highlight group for move mode
    },
    wrap_around = true, -- Wrap around edges when moving windows
    keymaps = {
        help = "?", -- Open floating window with help for the current mode
        help_close = "q", -- Close the floating help window
        quit = "q", -- Quit current mode
        move = {
            left = "h", -- Move window left
            down = "j", -- Move window down
            up = "k", -- Move window up
            right = "l", -- Move window right
            far_left = "H", -- Move window far left and maximize it
            far_down = "J", -- Move window down and maximize it
            far_up = "K", -- Move window up and maximize it
            far_right = "L", -- Move window right and maximize it
            split_left = "sh", -- Create a split with the window on the left
            split_down = "sj", -- Create a split with the window below
            split_up = "sk", -- Create a split with the window above
            split_right = "sl", -- Create a split with the window on the right
        },
    },
})

Autocommands

You can define autocommands that trigger when a mode starts and ends.

vim.api.nvim_create_autocmd("WinmoveModeStart", {
    callback = function(event)
        vim.print("Started ".. event.data.mode .. " mode")
    end,
})

vim.api.nvim_create_autocmd("WinmoveModeEnd", {
    callback = function(event)
        vim.print("Ended ".. event.data.mode .. " mode")
    end,
})

Public API

Warning

Consider only the functions below part of the public API. All other functions are subject to change.

winmove.configure

Configure winmove. Also see Configuration.

winmove.version

Get the current version of winmove.

winmove.current_mode

Check which mode is currently active. Returns "move" or nil.

winmove.start_mode

Start a mode.

---@param mode winmove.Mode
winmove.start_mode(mode)

-- Example:
winmove.start_mode(winmove.Mode.Move)
winmove.start_mode("move")

winmove.stop_mode

Stop the current mode. Fails if no mode is currently active.

winmove.move_window

Move a window (does not need to be the current window). See this showcase.

---@param win_id integer
---@param dir winmove.Direction
winmove.move_window(win_id, dir)

-- Example:
winmove.move_window(1000, "k")

winmove.split_into

Split into a window (does not need to be the current window). See this showcase.

---@param win_id integer
---@param dir winmove.Direction
winmove.split_into(win_id, dir)

-- Example:
winmove.split_into(1000, "l")

winmove.move_window_far

Move a window as far as possible in a direction (does not need to be the current window). See this showcase.

---@param win_id integer
---@param dir winmove.Direction
winmove.move_window_far(win_id, dir)

-- Example:
winmove.move_window_far(1000, "h")

Contributing

See here.

FAQ

Q: Why create this project?

A: There are already a few projects for moving windows but none of them felt intuitive to me so I did the only rational thing a developer would do in this situation and created my own plugin. If any of the others suit your needs then by all means use them.

Showcase

Moving around windows

Important

Moving windows takes into account the cursor position of the current window relative to the target window in the direction you are moving.

For example, if your cursor position is closest to the bottom of one window in the target direction, the window will be moved below that window. See this example for a visual explanation.

moving-around-windows.mov

Moving using relative cursor position

relative-cursor-position.mov

Splitting into windows

As opposed to moving windows, which will squeeze a window in between other windows, splitting into a window will move it next to a target window.

splitting-into-windows.mov

Moving as far as possible in a direction

moving-as-far-as-possible-in-a-direction.mov

Move between tabs

moving-between-tabs.mov

Works with asynchronous output

async-output.mov

Similar projects

• winshift.nvim
• vim-tradewinds