README.md

Neoterm.nvim

Simple floating terminal plugin for neovim written in Lua.

⚡ Installation

Requires neovim 0.7+ for access to the Lua Autocmd API.

lazy.nvim

{
    'itmecho/neoterm.nvim',
}

packer.nvim

use {
  'itmecho/neoterm.nvim',
}

💡 Usage

Neoterm provides both vim commands as well as a Lua API.

Configuration

The following functions are available on the neoterm module. They map directly to the commands above

-- Setup global config
require('neoterm').setup({
  clear_on_run = true, -- Run clear command before user specified commands
  position = 'right',  -- Position of the terminal window: fullscreen (0), top (1), right (2), bottom (3), left (4), center (5) (string or integer value)
  noinsert = false,    -- Disable entering insert mode when opening the neoterm window
  width = 0.5,         -- Width of the terminal window (percentage, ratio, or range between 0-1)
  height = 1,          -- Height of the terminal window (percentage, ratio, or range between 0-1)
})

local neoterm = require('neoterm')

neoterm.open()
-- Override global config on a specific open call
neoterm.open({ position = 'bottom', noinsert = true, width = 0.7, height = 0.3 })
neoterm.close()
neoterm.toggle()
neoterm.run('ls')
-- Control whether or not the screen is cleared before running the command
neoterm.run('ls', {clear = false})
neoterm.rerun()
neoterm.exit()

Deprecation Notice

Warning

The mode option is deprecated. Please use the new position option instead.

Migration Guide

• mode = vertical → position = right

• mode = horizontal → position = bottom

• mode = fullscreen → position = fullscreen

Commands

Neoterm provides the following commands

Command	Description
NeotermOpen	Open the neoterm window
NeotermClose	Close the neoterm window
NeotermToggle	Toggle the neoterm window
NeotermRun <args>	Run the given command in the neoterm window
NeotermRerun	Run the previous command again
NeotermExit	Close the neoterm window and delete the terminal buffer

Example Vim Keybindings

nnoremap <leader>tt <cmd>NeotermToggle<CR>
nnoremap <leader>tr :NeotermRun<space>
nnoremap <leader>tR <cmd>NeotermRerun<CR>
nnoremap <leader>tx <cmd>NeotermExit<CR>
tnoremap <leader>tn <C-\\><C-n>
tnoremap <leader>tt <cmd>NeotermToggle<CR>
tnoremap <leader>tx <cmd>NeotermExit<CR>

🔍 Screenshots

right

require('neoterm').open()
-- or
require('neoterm').open({ position = 'right' })
-- or
require('neoterm').open({ position = 2 })

top

require('neoterm').open({ position = 'top', height = 0.6 })

bottom

require('neoterm').open({ position = 'bottom' })
--or
require('neoterm').open({ position = 3 })

left

require('neoterm').open({ position = 'left', width = 0.3 })
-- or
require('neoterm').open({ position = 4 })

Contributors

Thanks to all contributors!