Vimcraft Docs / vim.opt - Editor Options

vim.opt - Editor Options

The vim.opt interface provides an ergonomic way to set editor options. All option names use camelCase (JavaScript convention), mapping to their Vim snake_case equivalents.

Display Options

Line Numbers

vim.opt.number = true;         // Show absolute line numbers
vim.opt.relativeNumber = true; // Show relative line numbers
// Both enabled: absolute on cursor line, relative on others

Cursor & Highlighting

vim.opt.cursorLine = true;     // Highlight current line
vim.opt.cursorColumn = true;   // Highlight current column
vim.opt.colorColumn = '80,120'; // Highlight columns 80 and 120

Sign Column

vim.opt.signColumn = 'yes';    // Always show sign column
vim.opt.signColumn = 'no';     // Never show
vim.opt.signColumn = 'auto';   // Show when there are signs
vim.opt.signColumn = 'number'; // Show signs in number column

Scrolling

vim.opt.scrollOff = 8;         // Keep 8 lines visible above/below cursor
vim.opt.sideScrollOff = 8;     // Keep 8 columns visible left/right

Status Line

vim.opt.lastStatus = 0;        // Never show status line
vim.opt.lastStatus = 1;        // Only if multiple windows
vim.opt.lastStatus = 2;        // Always show (default)
vim.opt.lastStatus = 3;        // Global status line

vim.opt.showCmd = true;        // Show partial command
vim.opt.showMode = true;       // Show mode (INSERT, VISUAL, etc.)
vim.opt.ruler = true;          // Show cursor position

Text Display

vim.opt.wrap = true;           // Wrap long lines
vim.opt.lineBreak = true;      // Wrap at word boundaries
vim.opt.termGuiColors = true;  // Enable 24-bit RGB colors
vim.opt.background = 'dark';   // 'dark' or 'light'

Invisible Characters

vim.opt.list = true;           // Show invisible characters
vim.opt.listChars = {
  tab: '→ ',                   // Tab character
  trail: '·',                  // Trailing spaces
  nbsp: '␣',                   // Non-breaking space
  eol: '¬',                    // End of line
  space: '·',                  // Regular spaces
  lead: '·',                   // Leading spaces
};

Folding

vim.opt.foldColumn = '1';      // Width of fold column
vim.opt.concealLevel = 0;      // 0-3, how to show concealed text

Editing Options

Tabs & Indentation

vim.opt.tabStop = 2;           // Spaces per tab character
vim.opt.shiftWidth = 2;        // Spaces for auto-indent
vim.opt.expandTab = true;      // Use spaces instead of tabs
vim.opt.softTabStop = 2;       // Spaces per Tab keypress

vim.opt.autoIndent = true;     // Copy indent from current line
vim.opt.smartIndent = true;    // Smart indenting for C-like code
vim.opt.smartTab = true;       // Tab inserts shiftWidth at line start

Text Width

vim.opt.textWidth = 80;        // Auto-wrap at 80 columns (0 = off)
vim.opt.formatOptions = 'tcq'; // Auto-format options

Editing Behavior

vim.opt.backspace = 'indent,eol,start'; // What backspace can delete
vim.opt.virtualEdit = 'block'; // Allow cursor past EOL in visual block
vim.opt.modifiable = true;     // Buffer can be modified
vim.opt.readOnly = false;      // Buffer is read-only

Search Options

vim.opt.ignoreCase = true;     // Case-insensitive search
vim.opt.smartCase = true;      // Case-sensitive if uppercase present
vim.opt.hlSearch = true;       // Highlight search matches
vim.opt.incSearch = true;      // Show matches while typing
vim.opt.wrapScan = true;       // Wrap search around file

Behavior Options

Mouse & Clipboard

vim.opt.mouse = 'a';           // Enable mouse in all modes
vim.opt.clipboard = 'unnamedplus'; // Use system clipboard

Undo & History

vim.opt.undoLevels = 1000;     // Number of undo levels
vim.opt.undoFile = true;       // Persistent undo
vim.opt.undoDir = '~/.vim/undo'; // Undo file directory

Timing

vim.opt.timeout = true;        // Time out on mappings
vim.opt.timeoutLen = 1000;     // Mapping timeout (ms)
vim.opt.updateTime = 300;      // CursorHold delay (ms)

Buffers & Files

vim.opt.hidden = true;         // Allow hidden buffers
vim.opt.autoRead = true;       // Auto-reload changed files
vim.opt.autoWrite = true;      // Auto-save when switching buffers
vim.opt.confirm = true;        // Confirm before abandoning unsaved

Backup & Swap

vim.opt.backup = false;        // Create backup files
vim.opt.writeBackup = true;    // Backup before overwriting
vim.opt.swapFile = false;      // Use swap files

Window Splits

vim.opt.splitRight = true;     // Vertical splits open right
vim.opt.splitBelow = true;     // Horizontal splits open below

UI Options

vim.opt.cmdHeight = 1;         // Command line height
vim.opt.pumHeight = 10;        // Popup menu max height
vim.opt.winBlend = 0;          // Window transparency (0-100)
vim.opt.pumBlend = 0;          // Popup menu transparency

vim.opt.showTabLine = 1;       // 0=never, 1=if multiple, 2=always
vim.opt.wildMenu = true;       // Enhanced command completion
vim.opt.wildMode = 'longest:full,full'; // Completion mode

Completion Options

vim.opt.completeOpt = 'menu,menuone,noselect'; // Completion behavior
vim.opt.showMatch = true;      // Briefly jump to matching bracket
vim.opt.spell = false;         // Enable spell checking

Complete Example

// ~/.config/vimcraft/index.ts

// Display
vim.opt.number = true;
vim.opt.relativeNumber = true;
vim.opt.cursorLine = true;
vim.opt.signColumn = 'yes';
vim.opt.scrollOff = 8;
vim.opt.termGuiColors = true;

// Indentation
vim.opt.tabStop = 2;
vim.opt.shiftWidth = 2;
vim.opt.expandTab = true;
vim.opt.smartIndent = true;

// Search
vim.opt.ignoreCase = true;
vim.opt.smartCase = true;
vim.opt.hlSearch = true;

// Behavior
vim.opt.mouse = 'a';
vim.opt.clipboard = 'unnamedplus';
vim.opt.hidden = true;
vim.opt.splitRight = true;
vim.opt.splitBelow = true;

// Performance
vim.opt.updateTime = 300;
vim.opt.timeoutLen = 500;

// No backup/swap
vim.opt.backup = false;
vim.opt.swapFile = false;

console.log('Options configured!');

Options Reference

Option	Type	Default	Description
`number`	boolean	false	Show line numbers
`relativeNumber`	boolean	false	Show relative line numbers
`cursorLine`	boolean	false	Highlight cursor line
`cursorColumn`	boolean	false	Highlight cursor column
`signColumn`	string	'auto'	Sign column display
`scrollOff`	number	0	Lines to keep above/below cursor
`tabStop`	number	8	Spaces per tab
`shiftWidth`	number	8	Spaces for indent
`expandTab`	boolean	false	Use spaces for tabs
`ignoreCase`	boolean	false	Case-insensitive search
`smartCase`	boolean	false	Smart case sensitivity
`hlSearch`	boolean	false	Highlight search matches
`wrap`	boolean	true	Wrap long lines
`mouse`	string	''	Mouse support modes
`clipboard`	string	''	Clipboard integration
`splitRight`	boolean	false	Vertical splits go right
`splitBelow`	boolean	false	Horizontal splits go below