Core API Functions

Core nvim_* functions provide global operations for the Neovim editor, including input handling, buffer/window/tabpage management, variables, and more.

Input and Execution

nvim_feedkeys()

Sends input-keys to Nvim, subject to various quirks controlled by mode flags. This is a blocking call.

keys

string

required

Keys to be typed

mode

string

required

Behavior flags (see :h feedkeys())

'n': No remapping
'm': Remapping allowed
't': Handle keys as if typed
'i': Insert at start of typebuf
'x': Execute keys immediately

escape_ks

boolean

required

If true, escape K_SPECIAL bytes in keys. Should be false if you already used nvim_replace_termcodes()

vim.api.nvim_feedkeys('iHello', 'n', false)

-- With termcodes
local key = vim.api.nvim_replace_termcodes('<C-o>', true, false, true)
vim.api.nvim_feedkeys(key, 'n', false)

nvim_input()

Queues raw user-input. Unlike nvim_feedkeys(), this uses a low-level input buffer and is non-blocking.

keys

string

required

Keys to be typed

return

integer

Number of bytes actually written

local bytes = vim.api.nvim_input('ihello<Esc>')
print('Wrote ' .. bytes .. ' bytes')

nvim_exec_lua()

Executes Lua code. Arguments are available as ... inside the chunk.

code

string

required

Lua code to execute

args

array

required

Arguments to the Lua code

return

any

Value returned by the Lua code (if any), or NIL

local result = vim.api.nvim_exec_lua([[
  local a, b = ...
  return a + b
]], {5, 10})
print(result)  -- 15

Buffer Management

nvim_list_bufs()

Gets the current list of buffers. Includes unlisted (unloaded/deleted) buffers.

return

integer[]

List of buffer handles (buffer numbers)

local buffers = vim.api.nvim_list_bufs()
for _, buf in ipairs(buffers) do
  print('Buffer: ' .. buf)
end

nvim_get_current_buf()

Gets the current buffer.

return

integer

Buffer handle

nvim_set_current_buf()

Sets the current window’s buffer.

buffer

integer

required

Buffer handle

nvim_create_buf()

Creates a new, empty, unnamed buffer.

listed

boolean

required

Sets ‘buflisted’

scratch

boolean

required

Creates a scratch buffer (always ‘nomodified’)

return

integer

Buffer handle, or 0 on error

-- Create a listed buffer
local buf = vim.api.nvim_create_buf(true, false)

-- Create a scratch buffer
local scratch = vim.api.nvim_create_buf(false, true)

Window Management

nvim_list_wins()

Gets the current list of all window IDs in all tabpages.

return

integer[]

List of window handles

nvim_get_current_win()

Gets the current window.

return

integer

Window handle

nvim_set_current_win()

Navigates to the given window (and tabpage, implicitly).

window

integer

required

Window handle

Tabpage Management

nvim_list_tabpages()

Gets the current list of tabpage IDs.

return

integer[]

List of tabpage handles

nvim_get_current_tabpage()

Gets the current tabpage.

return

integer

Tabpage handle

nvim_set_current_tabpage()

Sets the current tabpage.

tabpage

integer

required

Tabpage handle

Variables

nvim_get_var()

Gets a global (g:) variable.

name

string

required

Variable name

return

any

Variable value

nvim_set_var()

Sets a global (g:) variable.

name

string

required

Variable name

value

any

required

Variable value

nvim_del_var()

Removes a global (g:) variable.

name

string

required

Variable name

nvim_get_vvar()

Gets a v: variable.

name

string

required

Variable name

return

any

Variable value

Current Line Operations

nvim_get_current_line()

Gets the current line.

return

string

Current line string

nvim_set_current_line()

Sets the text on the current line.

line

string

required

Line contents

nvim_del_current_line()

Deletes the current line.

Highlights

nvim_get_hl_id_by_name()

Gets a highlight group by name. Similar to hlID(), but allocates a new ID if not present.

name

string

required

Highlight group name

return

integer

Highlight group ID

nvim_set_hl()

Sets a highlight group.

ns_id

integer

required

Namespace id (use 0 for global)

name

string

required

Highlight group name (e.g., “ErrorMsg”)

val

table

required

Highlight definition map with keys:

fg: foreground color
bg: background color
bold: boolean
italic: boolean
underline: boolean
link: name of another group to link to

-- Set a highlight group
vim.api.nvim_set_hl(0, 'MyHighlight', {
  fg = '#ff0000',
  bg = '#000000',
  bold = true
})

-- Link to another group
vim.api.nvim_set_hl(0, 'MyHighlight2', {
  link = 'ErrorMsg'
})

nvim_get_hl()

Gets all or specific highlight groups in a namespace.

ns_id

integer

required

Namespace id (use 0 for global)

opts

table

required

Options:

name: Get by name
id: Get by id
link: Show linked group name

return

table

Highlight definition map

Utility Functions

nvim_get_mode()

Gets the current mode.

return

table

Dictionary with keys:

mode: Mode short-name string
blocking: Boolean, true if waiting for input

local mode = vim.api.nvim_get_mode()
print('Mode: ' .. mode.mode)
print('Blocking: ' .. tostring(mode.blocking))

nvim_strwidth()

Calculates the number of display cells occupied by text.

text

string

required

Some text

return

integer

Number of cells

nvim_get_api_info()

Returns a 2-tuple with current channel id and API metadata.

return

array

Array [{channel-id}, {api-metadata}]

Introduction

API Functions

Advanced

Client Development

​Core API Functions

​Input and Execution

​nvim_feedkeys()

​nvim_input()

​nvim_exec_lua()

​Buffer Management

​nvim_list_bufs()

​nvim_get_current_buf()

​nvim_set_current_buf()

​nvim_create_buf()

​Window Management

​nvim_list_wins()

​nvim_get_current_win()

​nvim_set_current_win()

​Tabpage Management

​nvim_list_tabpages()

​nvim_get_current_tabpage()

​nvim_set_current_tabpage()

​Variables

​nvim_get_var()

​nvim_set_var()

​nvim_del_var()

​nvim_get_vvar()

​Current Line Operations

​nvim_get_current_line()

​nvim_set_current_line()

​nvim_del_current_line()

​Highlights

​nvim_get_hl_id_by_name()

​nvim_set_hl()

​nvim_get_hl()

​Utility Functions

​nvim_get_mode()

​nvim_strwidth()

​nvim_get_api_info()

​See Also

Build docs developers (and LLMs) love

Core API Functions

Input and Execution

nvim_feedkeys()

nvim_input()

nvim_exec_lua()

Buffer Management

nvim_list_bufs()

nvim_get_current_buf()

nvim_set_current_buf()

nvim_create_buf()

Window Management

nvim_list_wins()

nvim_get_current_win()

nvim_set_current_win()

Tabpage Management

nvim_list_tabpages()

nvim_get_current_tabpage()

nvim_set_current_tabpage()

Variables

nvim_get_var()

nvim_set_var()

nvim_del_var()

nvim_get_vvar()

Current Line Operations

nvim_get_current_line()

nvim_set_current_line()

nvim_del_current_line()

Highlights

nvim_get_hl_id_by_name()

nvim_set_hl()

nvim_get_hl()

Utility Functions

nvim_get_mode()

nvim_strwidth()

nvim_get_api_info()

See Also