Skip to main content
The lua/user/options.lua file contains all the core Neovim options that control editor behavior, appearance, and functionality.

​
Overview

Options are configured using a table that gets applied to vim.opt. This file sets up essential editor settings like clipboard integration, indentation, search behavior, and UI preferences.

​
Configuration Structure

All options are defined in a single table and applied using a loop:
lua/user/options.lua
local options = {
  -- your options here
}

for k, v in pairs(options) do
  vim.opt[k] = v
end

​
File Management

backup = false        -- Disables backup files
swapfile = false      -- Disables swap files
writebackup = false   -- No backup before overwriting a file
undofile = true       -- Enable persistent undo history
The configuration disables traditional backup and swap files but enables persistent undo, allowing you to undo changes even after closing and reopening a file.
fileencoding = "utf-8"  -- Encoding written to files
All files are saved with UTF-8 encoding by default.

​
Editing Behavior

​
Indentation

OptionValueDescription
expandtabtrueConvert tabs to spaces
shiftwidth2Number of spaces for each indentation level
tabstop2Number of spaces for a tab character
smartindenttrueSmart autoindenting on new lines

​
Text Wrapping

wrap = true        -- Display long lines as multiple lines
linebreak = true   -- Break lines at word boundaries

​
Clipboard Integration

clipboard = "unnamedplus"  -- Use system clipboard
This allows you to copy and paste between Neovim and other applications seamlessly.

​
Search Configuration

Case Sensitivity

ignorecase = true  -- Ignore case in searches
smartcase = true   -- Override ignorecase if search contains uppercase

Highlighting

hlsearch = true  -- Highlight all search matches

​
UI and Display

​
Line Numbers

number = true           -- Show line numbers
relativenumber = false  -- Disable relative line numbers
numberwidth = 4         -- Width of the line number column

​
Visual Indicators

OptionValueDescription
cursorlinetrueHighlight the current line
signcolumn"yes"Always show sign column (for git, diagnostics, etc.)
showmodefalseDon’t show mode (INSERT, VISUAL, etc.) in command line
showtabline2Always show tab line

​
Scrolling

scrolloff = 8       -- Minimum lines to keep above/below cursor
sidescrolloff = 8   -- Minimum columns to keep left/right of cursor
These settings ensure the cursor never gets too close to the edge of the screen.

​
Split Windows

splitbelow = true   -- Horizontal splits open below
splitright = true   -- Vertical splits open to the right

​
Completion and Popup

completeopt = { "menuone", "noselect" }  -- Completion menu behavior
pumheight = 10                           -- Maximum items in popup menu

​
Performance and Timing

These settings affect how responsive Neovim feels and how quickly it triggers certain events.
timeoutlen = 300   -- Time to wait for mapped sequence (ms)
updatetime = 300   -- Time before swap file is written (ms)
  • timeoutlen: Affects how quickly key combinations must be typed
  • updatetime: Controls how quickly CursorHold events fire (affects diagnostics, git signs, etc.)

​
Advanced Options

​
Command Line

cmdheight = 2  -- Height of the command line area
Provides more space for displaying messages and command output.

​
Mouse Support

mouse = "a"  -- Enable mouse in all modes

​
Markdown Concealment

conceallevel = 0  -- Don't hide syntax (e.g., `` in markdown)

​
Font Configuration

guifont = "monospace:h17"  -- Font for GUI Neovim (e.g., Neovide)

whichwrap = "bs<>[]hl"  -- Keys that can move to previous/next line
Allows Backspace, Space, arrow keys, and h/l to wrap to the next/previous line.

​
Additional Settings

These settings are applied after the main options table:

​
Short Messages

vim.opt.shortmess:append "c"
Don’t show completion menu messages.

​
Keyword Recognition

vim.opt.iskeyword:append "-"
Treats hyphenated words as a single word for navigation and search.

​
Format Options

vim.opt.formatoptions:remove({ "c", "r", "o" })
Prevents automatic comment continuation on new lines.

​
Runtime Path

vim.opt.runtimepath:remove("/usr/share/vim/vimfiles")
Separates Neovim plugins from Vim plugins.

​
Customization Tips

To modify any option, simply change the value in the options table and restart Neovim or source the file with :luafile %.
relativenumber = true  -- Change from false to true

​
See Also

Keymaps

Configure custom key bindings

Autocommands

Set up automatic commands

Build docs developers (and LLMs) love

Get started for freeTalk to us