TermLayout

Overview

• It lets you keep reusable terminals around and switch between bottom layouts, right-side layouts, and dedicated terminal tabpages.
• It is designed for users who want fast terminal access without giving up their current editor split layout.
• After daily use and substantial implementation changes to fit a personal workflow, it changed enough from CRAG666/betterTerm.nvim to become its own standalone plugin.

Requirements

• Neovim (>= 0.10)

Install

• With Lazy

{
  "luckpoint/termlayout.nvim",
  opts = {
    -- your options
  },
}

Testing

The repository includes a dependency-free headless Neovim E2E suite under tests/e2e/.

• Run the full suite: ./tests/e2e/run.sh
• Run a single spec by basename: ./tests/e2e/run.sh ui_stubs
• Run a specific file: ./tests/e2e/run.sh tests/e2e/specs/winbar_termrequest_spec.lua
• Override the Neovim binary when needed: NVIM_BIN=/path/to/nvim ./tests/e2e/run.sh

The runner starts a fresh headless Neovim process for each spec, so terminal state, layout state, and UI stubs stay isolated between cases.

Quick start

Common actions

• open(id?, opts?): Open, focus, create, or hide a terminal. id can be a global terminal index or buffer name. Defaults to 0. opts.cwd sets the working directory for a new terminal.
• select(): Open a terminal picker. Includes a New entry. Selecting a hidden terminal from a terminal window replaces the current terminal pane.
• rename(new_name?): Rename the current terminal. Prompts when new_name is omitted.
• toggle_termwindow(): Toggle between the current editor-only view and the previously used terminal layout. Falls back to horizontal_single.
• layout(name): Switch to a preset layout.
• layout_select(): Open a layout picker.
• layout_toggle(): Show or hide the active layout.

Additional API

• close(id?): Close a terminal by global terminal index or buffer name. Defaults to 0.
• send(command, index?, press?): Send a command to a terminal. Omitting index targets terminal 0. press.interrupt sends <C-c> first, press.clean sends <C-l> first.
• send_prompt(index?, opts?): Open a 3-line floating input, then send the submitted command to terminal 0 by default. <C-j> and <S-CR> insert a newline. If the last line is blank, one extra <CR> is sent after 1 second.
• cycle(shift?): Move focus left or right among displayed terminals. Defaults to 1.
• focus_visible(display_index): Focus a currently visible terminal by its 1-based UI index. Returns true on success.
• layout_info(): Return the current layout state as a table with name, visible, slots, and winids.
• toggle_tabs(): Toggle the terminal winbar labels outside preset layouts.

Layout Patterns

Pattern	Slots	Description
editor	0	Editor only, hide the terminal preset
horizontal_single	1	Keep the current editor layout and show one terminal at the bottom
vertical_single	1	Keep the current editor layout and show one terminal in a right-side column
horizontal_split	2	Keep the current editor layout and show two terminals side by side at the bottom
horizontal_triple	3	Keep the current editor layout and show three terminals side by side at the bottom
vertical_split	2	Keep the current editor layout and show two terminals stacked in a right-side column
vertical_triple	3	Keep the current editor layout and show three terminals stacked in a right-side column
quad	4	Open a dedicated 2x2 terminal workspace in a separate tabpage
fullscreen	1	Open a dedicated fullscreen terminal in a separate tabpage

Layout Screenshots

Layout	Layout	Layout
editor	horizontal_single	vertical_single
horizontal_split	horizontal_triple	vertical_split
vertical_triple	quad	fullscreen

Layout Commands

• :TermLayout <name> - Switch to a layout (tab-completion supported)
• :TermLayoutToggle - Toggle layout visibility
• :TermLayoutSelect - Open a layout picker

Recommended keymaps

No keymaps are set by default. A minimal setup looks like this:

local tl = require("termlayout")

vim.keymap.set({ "n", "t" }, "<C-;>", tl.open, { desc = "Toggle terminal" })
vim.keymap.set("n", "<leader>tt", tl.select, { desc = "Select terminal" })
vim.keymap.set("n", "<leader>tp", tl.layout_select, { desc = "Select layout" })
vim.keymap.set("n", "<leader>tl", tl.layout_toggle, { desc = "Toggle layout" })
vim.keymap.set("n", "<leader>tw", tl.toggle_termwindow, { desc = "Toggle terminal workspace" })

for n = 1, 9 do
  vim.keymap.set({ "n", "t" }, "<leader>ji" .. n, function()
    tl.send_prompt(n - 1)
  end, { desc = "Send command to terminal " .. n })
end

Add direct mappings for specific layouts only if you use them frequently, for example horizontal_split, vertical_split, or quad.

Configuration

You can configure the plugin by passing a table to the setup function.

-- Example configuration
require('termlayout').setup {
  vertical_size = 20,
  horizontal_size = math.floor(vim.o.columns / 2),
}

Options

• vertical_size (number, default: vim.o.lines / 2): Height used for bottom terminal layouts and bottom terminal windows.
• horizontal_size (number, default: vim.o.columns / 2): Width used for right-side terminal layouts and narrow terminal windows.
• show_tabs (boolean, default: true): Enable/Disable the tabs bar.
• new_tab_mapping (string, default: <C-t>): Mapping to create a new terminal from within a terminal buffer.
• label_hl (string, default: TabLineSel): Highlight group for the terminal label shown in the winbar.

Terminal IDs are fixed to start at 0. The winbar and picker labels remain 1-based.

Compatibility notes

• size has been replaced by vertical_size and horizontal_size.
• index_base has been removed. Terminal IDs always start at 0.
• active_tab_hl has been renamed to label_hl.
• inactive_tab_hl has been removed because it was unused.
• Old layout names single, horizontal-split, and triple are still accepted, but they emit a warning and map to the new names.

Default values

require('termlayout').setup {
 vertical_size = math.floor(vim.o.lines / 2),
 horizontal_size = math.floor(vim.o.columns / 2),
 show_tabs = true,
 new_tab_mapping = "<C-t>",
 label_hl = "TabLineSel",
}

Example lazy.nvim config

return {
  'luckpoint/termlayout.nvim',
  keys = {
    {
      mode = { 'n', 't' },
      '<C-;>',
      function()
        require('termlayout').open()
      end,
      desc = 'Open TermLayout 0',
    },
    {
      mode = { 'n', 't' },
      '<C-/>',
      function()
        require('termlayout').open(1)
      end,
      desc = 'Open TermLayout 1',
    },
    {
      '<leader>tt',
      function()
        require('termlayout').select()
      end,
      desc = 'Select terminal',
    }
  },
  opts = {
    vertical_size = 20,
    horizontal_size = math.floor(vim.o.columns / 2),
  },
}

Credits

Forked from CRAG666/betterTerm.nvim.