All features can be toggled independently in Settings → Vim Motions. Changes take effect immediately without restarting. Settings are organized into 7 pages for easier navigation:
Page
Settings groups
General
Mobile, Vim features, Picker, Vim engine
Appearance
Line numbers, Gutter, Status bar, Vim mode display prompt, Cursor shapes, Animated cursor, Yank highlight
On Obsidian 1.13+, pages appear as navigable entries in the settings sidebar. On earlier versions, a tab bar at the top of the settings panel lets you switch between pages. All settings are indexed by Obsidian’s global settings search (1.13+).
Mobile
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Enable on mobile
toggle
false
—
—
—
Activate the plugin on mobile devices. Disabled by default because most mobile users lack a hardware keyboard.
Tip
Changing this setting requires an Obsidian reload. You can also toggle it from the command palette: Vim Motions: Toggle enable on mobile.
Vim features
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Text objects
toggle
true
—
vim.opt.textobjects
set textobjects
Enable Markdown-aware text objects (i*, a*, il, etc.).
Replace-with-register operator
toggle
true
—
vim.opt.replacewithregister
set replacewithregister
Enable the gr operator to replace text with register contents. Also available via :set rwr and vim.opt.rwr.
Structural navigation
toggle
true
—
vim.opt.navigation
set navigation
Enable heading, list, and link navigation motions (]h, [h, ]l, etc.).
Hard-wrap operator (gq)
toggle
true
—
vim.opt.hardwrap
set hardwrap
Enable gq operator to reformat paragraphs with Markdown-aware line wrapping.
Smart list continuation on o/O
toggle
true
—
vim.opt.listcontinuation
set listcontinuation
Automatically continue list markers (bullets, numbers, checkboxes) when pressing o or O.
Table navigation
toggle
true
—
vim.opt.tablenav
set tablenav
Enable table-nav overlay mode and table motions (]| , [| , ]c, [c). When disabled, the native table editor still supports vim cell editing with cross-cell h/j/k/l navigation.
Table widget in live preview
dropdown
native
native, raw
vim.opt.tablewidget
set tablewidget
Controls how tables display in Live Preview. native uses Obsidian’s built-in table editor with vim injected into cell editors. raw always shows raw markdown.
Cycle through numbered registers after paste (<C-p>/<C-n>).
Sign column
dropdown
auto
auto[:N], yes[:N], no
vim.opt.signcolumn
set signcolumn
Show vim mark letters in a dedicated gutter column. Auto: show when marks exist. Always: always reserve space. Off: hide. Append :N (1–4) to set character width. Clickable — clicking a mark jumps to its line. Global marks (A–Z) shown in distinct color.
Fold column
toggle
false
—
vim.opt.foldcolumn
set foldcolumn
Show fold indicators (▸/▾) in the gutter for foldable regions. Click to toggle. Default: off.
Vim keybindings in text areas
toggle
false
—
vim.opt.vimtextareas
set vimtextareas
Replace focused text areas with a vim-enabled editor. Starts in insert mode. Experimental, desktop only.
Subword motions
toggle
false
—
vim.opt.subword
set subword
Override w/b/e/ge to stop at camelCase, snake_case, and kebab-case boundaries.
Enhanced increment/decrement
toggle
false
—
vim.opt.dial
set dial
Extends <C-a>/<C-x> to cycle hex colors, booleans, dates, CSS values, and checkboxes.
Tip
Override the highlight color with a CSS snippet: set --vim-motions-yank-bg on .theme-dark or .theme-light (e.g., --vim-motions-yank-bg: rgba(255, 200, 0, 0.4);).
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Workspace navigation
toggle
true
—
vim.opt.workspacenav
set workspacenav
Enable pane/tab/sidebar control (<C-w>h/j/k/l, gt, gT, etc.).
Fuzzy picker for buffers
toggle
true
—
—
—
Use the unified fuzzy picker for :buffers, :ls, :marks, :registers, and :grep.
Picker leader mappings
toggle
true
—
—
—
Enable default <leader>f* picker mappings and which-key labels.
Picker matching engine
dropdown
ufuzzy
ufuzzy, obsidian
—
—
Fuzzy matching engine. uFuzzy is a fast pure-JS matcher with filename-aware ranking. Obsidian uses the built-in prepareFuzzySearch API.
Workspace navigation view types
text
(empty)
—
vim.opt.workspacenavviewtypes
set workspacenavviewtypes
Comma-separated view types where scroll and count keys are intercepted. Empty uses defaults (markdown, graph, pdf, canvas, empty, image, bases).
Fold-aware navigation
toggle
true
—
vim.opt.foldawarenavigation
set foldawarenavigation
Automatically unfold sections when navigating into them (e.g., ]h into a folded heading). Matches Neovim’s default foldopen behavior.
Fold persistence
toggle
false
—
vim.opt.foldpersistence
set foldpersistence
Remember fold state across file switches and sessions. Capped at 500 files, 30-day TTL.
Fold enable/disable
toggle
true
—
vim.opt.foldenable
set foldenable
Enable or disable folding. When disabled (zn), all folds are opened and fold-creating commands become no-ops. Re-enable with zN or zi.
Warning
Workspace navigation: <C-w>, Ctrl-d, Ctrl-f, and Ctrl-b may conflict with Obsidian’s default hotkeys. The plugin detects these conflicts on startup and shows a Notice. Use the Check hotkey conflicts button in this settings group to see active conflicts and unbinding instructions.
Picker
Info
Ripgrep integration is desktop-only and requires the rg binary to be installed on your system.
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Use ripgrep for grep/live-grep
toggle
false
—
—
—
Use a local ripgrep binary for faster vault search.
Ripgrep binary path
text
(empty)
—
—
—
Absolute path to the rg binary.
Ripgrep extra arguments
text
--smart-case --glob "*.md"
—
—
—
Additional arguments passed to ripgrep.
Vim engine
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Clipboard
dropdown
(off)
unnamed, unnamedplus, (off)
vim.opt.clipboard
set clipboard
Sync yank/delete/paste with the system clipboard. When set, p falls back to Obsidian’s native paste for non-text clipboard content (images, files), creating an attachment and inserting an image embed.
Tabstop
slider
4
1–8
vim.opt.tabstop
set tabstop
Tab display width.
Shiftwidth
slider
4
1–8
vim.opt.shiftwidth
set shiftwidth
Indent width.
Expand tab
toggle
true
—
vim.opt.expandtab
set expandtab
Use spaces instead of tabs.
PCRE
toggle
true
—
vim.opt.pcre
set pcre
Use JavaScript regular expressions in search and substitution. When off (set nopcre), uses Vim-style regex syntax.
Insert mode escape
text
(off)
—
vim.opt.insertmodeescape
set insertmodeescape
Two-key sequence to exit insert mode (e.g., jk).
Insert mode escape timeout
number
1000
100–5000
vim.opt.insertmodeescapetimeout
set insertmodeescapetimeout
Timeout in milliseconds for insert mode escape sequence.
Operator shadow timeout
number
1000
0–5000
vim.opt.operatorshadowtimeout
set operatorshadowtimeout
Timeout in milliseconds for operator-prefix disambiguation. When an operator is pending and the next key matches both a motion and an operator-pending action prefix (e.g. surround), waits this long before falling back to the motion. Set to 0 to disable.
Textwidth
number
80
0–200
vim.opt.textwidth
set textwidth
Line wrap width for gq/gw (0 to disable).
Line numbers
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Line numbers
toggle
false
—
vim.opt.number
set number
Show absolute line numbers in the gutter. Default: off.
Relative line numbers
toggle
false
—
vim.opt.relativenumber
set relativenumber
Show relative line numbers (distance from cursor). When both are enabled, shows hybrid mode (absolute on current line, relative on others). Default: off.
Number width
slider
2
1–20
vim.opt.numberwidth
set numberwidth
Minimum width of the line number column in characters (1–20). Default: 2.
Line number display
dropdown
hybrid
hybrid, dual, dual-rel-abs
vim.opt.linenumbermode
set linenumbermode
Deprecated — use statuscolumn. Dual maps to statuscolumn="%l %r".
Cursor line highlight
toggle
true
—
vim.opt.cursorline
set cursorline
Highlight the current cursor line. Default: on.
Cursor line highlight mode
dropdown
number
number, line, both
vim.opt.cursorlineopt
set cursorlineopt
What to highlight — Number, Line, or Both. Default: Number.
Custom gutter layout with statuscolumn
Use vim.opt.statuscolumn in Lua or set statuscolumn in vimrc to fully customize the gutter area. Supported tokens: %l (line number), %r (relative number), %s (signs), %C (fold indicators), %= (separator).
When all gutter columns are active, the layout from left to right is: sign column → line numbers → fold column → content. This matches Neovim’s default arrangement.
Example with hybrid line numbers (number + relativenumber), sign column, and fold column enabled — cursor on line 8:
a 3 ▸ ## Introduction
2 Some text here.
1 More context.
8 ← cursor line (absolute number)
1 Additional notes.
b 2 Another paragraph.
3 Final thoughts.
Jump navigation
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Flash-style f/F/t/T
toggle
true
—
vim.opt.flash
set flash
Show labels on all visible matches for f/F/t/T motions.
Flash multi-line
toggle
true
—
vim.opt.flashmultiline
set flashmultiline
Search beyond the current line for f/F/t/T matches.
Dim non-target text when EasyMotion or flash is active.
EasyMotion label characters
text
asdghklqwertyuiopzxcvbnmfj
—
vim.opt.easymotionlabels
set easymotionlabels
Characters used for EasyMotion and flash labels.
Hint mode
toggle
true
—
vim.opt.hintmode
set hintmode
Enable vimium-style link hints to click UI elements.
Hint mode label characters
text
asdfghjkl
—
vim.opt.hintlabels
set hintlabels
Characters used for hint labels.
Hint mode global hotkey
hotkey
(off)
—
—
—
Key combination to trigger hint mode from anywhere.
Label font size
slider
14
10–20
vim.opt.labelfontsize
set labelfontsize
Font size for EasyMotion and hint mode labels.
Scale labels to line height
toggle
false
—
vim.opt.labelmatchfontsize
set labelmatchfontsize
Scale label font to match the target line’s font size.
Harpoon file pinning
toggle
true
—
vim.opt.harpoon
set harpoon
Pin files to numbered slots for instant switching.
Vimrc / Lua only
The following options are available via vimrc and Lua but do not appear in the Settings UI:
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Jump list
toggle
true
—
vim.opt.jumplist
set jumplist
Use vim-style jump list for <C-o>/<C-i>.
Jump list size
number
200
1–1000
vim.opt.jumplistsize
set jumplistsize
Maximum number of entries in the jump list.
Update time
number
4000
ms
vim.opt.updatetime
set updatetime
Milliseconds before CursorHold fires. Matches Neovim’s updatetime.
Snippets
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Enable snippets
toggle
true
—
vim.opt.snippets
set snippets
Master toggle for snippet expansion.
Bundled snippets
toggle
true
—
vim.opt.snippetbundled
set snippetbundled
Include built-in Obsidian markdown snippets.
Snippet directory
text
(off)
—
vim.opt.snippetdir
set snippetdir
Path to a directory with user snippet JSON files.
Trigger mode
dropdown
both
completion, tab, both
vim.opt.snippettrigger
set snippettrigger
How snippets are triggered: completion menu, Tab, or both.
File explorer
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Oil explorer
toggle
true
—
vim.opt.oilexplorer
set oilexplorer
Enable the oil-style file explorer (:Oil command).
Show hidden files
toggle
false
—
vim.opt.oilshowhiddenfiles
set oilshowhiddenfiles
Show dotfiles and hidden folders in oil views.
Confirm delete threshold
slider
1
1–20
vim.opt.oilconfirmdeletethreshold
set oilconfirmdeletethreshold
Show confirmation when deleting this many files or more.
Default sort order
dropdown
name
name, mtime, size
vim.opt.oildefaultsort
set oildefaultsort
Default sort order for oil directory listings.
Undo tree
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Undo tree
toggle
true
—
vim.opt.undotree
set undotree
Track branching undo history for g+/g- navigation, :earlier/:later, and :undolist output.
Persist undo history
toggle
false
—
vim.opt.undofile
set undofile
Save per-file undo history to plugin data so it survives across sessions (like set undofile).
Maximum undo tree nodes
slider
1000
100–5000
vim.opt.undotreemaxnodes
set undotreemaxnodes
Maximum number of undo states to keep per editor. Oldest leaf branches are pruned when exceeded.
Sidebar position
dropdown
right
left, right
—
—
Which sidebar to open the undo tree view in.
Auto-open on branch
toggle
false
—
—
—
Automatically open the undo tree sidebar when a branch is created (undo + new edit).
Animated cursor
Setting
Key
Type
Default
Description
Enable animated cursor
animatedCursor
Toggle
Off
Master toggle for canvas-based cursor rendering
Smooth cursor movement
smoothCursor
Toggle
On
Cursor glides between positions instead of teleporting
Cursor smoothness
cursorSmoothness
Slider 0–1
0.5
How lazy the cursor movement feels (0 = snap, 1 = very slow)
Enable smear trail
smearTrail
Toggle
On
Spring-damper trail stretching between old and new position
Trail stiffness
smearStiffness
Slider 0.1–1
0.6
Head corner spring strength
Trail trailing stiffness
smearTrailingStiffness
Slider 0.1–1
0.3
Tail corner spring strength
Trail damping
smearDamping
Slider 0.1–0.99
0.85
Velocity decay (lower = bouncier)
Trail max length
smearMaxLength
Slider 50–800
400
Maximum trail length in pixels
Status bar
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Vim mode status bar
toggle
true
—
vim.opt.statusbar
set statusbar
Show current Vim mode in the status bar.
Vim chord display
toggle
true
—
vim.opt.chorddisplay
set chorddisplay
Show pending keystrokes in the status bar.
Powerline-style status bar
toggle
false
—
vim.opt.powerline
set powerline
Color the Vim mode indicator with per-mode background colors.
Vim mode display prompt
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Normal mode prompt
text
NORMAL
—
vim.g.mode_prompt_normal
let g:mode_prompt_normal
Status bar text for normal mode.
Insert mode prompt
text
INSERT
—
vim.g.mode_prompt_insert
let g:mode_prompt_insert
Status bar text for insert mode.
Visual mode prompt
text
VISUAL
—
vim.g.mode_prompt_visual
let g:mode_prompt_visual
Status bar text for visual mode.
V-Line mode prompt
text
V-LINE
—
vim.g.mode_prompt_visual_line
let g:mode_prompt_visual_line
Status bar text for visual line mode.
V-Block mode prompt
text
V-BLOCK
—
vim.g.mode_prompt_visual_block
let g:mode_prompt_visual_block
Status bar text for visual block mode.
Replace mode prompt
text
REPLACE
—
vim.g.mode_prompt_replace
let g:mode_prompt_replace
Status bar text for replace mode.
Select mode prompt
text
SELECT
—
vim.g.mode_prompt_select
let g:mode_prompt_select
Status bar text for select mode.
Virtual replace mode prompt
text
V-REPLACE
—
vim.g.mode_prompt_vreplace
let g:mode_prompt_vreplace
Status bar text for virtual replace mode.
Command mode prompt
text
COMMAND
—
vim.g.mode_prompt_command
let g:mode_prompt_command
Status bar text for command-line mode.
Search mode prompt
text
SEARCH
—
vim.g.mode_prompt_search
let g:mode_prompt_search
Status bar text for search mode.
Insert-normal mode prompt
text
NORMAL
—
vim.g.mode_prompt_insert_normal
let g:mode_prompt_insert_normal
Status bar text when in normal mode via Ctrl-O from insert.
Cursor shapes
Info
Cursor shapes require bundled fork mode. Disable Obsidian’s built-in Vim key bindings to enable these options.
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Normal mode
dropdown
block
block, bar, underline, hollow
—
set guicursor
Cursor shape for normal mode.
Insert mode
dropdown
bar
block, bar, underline, hollow
—
set guicursor
Cursor shape for insert mode.
Visual mode
dropdown
block
block, bar, underline, hollow
—
set guicursor
Cursor shape for visual mode.
Replace mode
dropdown
underline
block, bar, underline, hollow
—
set guicursor
Cursor shape for replace mode.
Operator-pending
dropdown
underline
block, bar, underline, hollow
—
set guicursor
Cursor shape for operator-pending mode.
Vimrc & key bindings
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Configuration mode
dropdown
lua-vimrc
lua-vimrc, lua, vimrc, settings
—
—
How the plugin loads config files. Lua + Vimrc loads both with Lua priority.
Custom vimrc path
text
(empty)
—
—
—
Override path to a vimrc file. Vault-relative or absolute (desktop only, e.g. ~/.config/obsidian/vimrc). Leave empty to search: vimrc, .vimrc, init.vim, .init.vim, obsidian.vimrc, obsidian.vim, .obsidian.vimrc, .obsidian.vim.
Custom init.lua path
text
(empty)
—
—
—
Override path to an init.lua file. Vault-relative or absolute (desktop only, e.g. ~/.config/obsidian/init.lua). Leave empty to search: init.lua, .init.lua, obsidian.init.lua, .obsidian.init.lua, obsidian.lua.
Show config load notifications
toggle
on
—
—
—
Show a notification when vimrc or init.lua is loaded on startup. Error notifications are always shown regardless of this setting.
Leader key bindings
Map leader key sequences to Obsidian commands. This UI allows you to add new bindings by specifying a key sequence and picking an Obsidian command from a searchable list. Existing bindings can be removed via the trash icon. These are applied in addition to any bindings defined in your vimrc.
Which-key hints
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Which-key mode
dropdown
off
off, leader, all
vim.opt.whichkey
set whichkey
Show available key continuations in a popup.
Which-key leader grouping
dropdown
grouped
grouped, flat
vim.opt.whichkeygrouping
set whichkeygrouping
How leader key bindings are displayed.
Which-key sort order
dropdown
which-key
which-key, groups-first
vim.opt.whichkeysort
set whichkeysort
How entries are sorted. which-key matches which-key.nvim (keys first, groups last, alphanumeric before special). groups-first shows groups before keys, alphabetically.
Which-key icons
toggle
true
—
vim.opt.whichkeyicons
set whichkeyicons
Show icons next to entries in the which-key popup. Built-in groups show default Lucide icons.
Which-key popup delay
number
500
0–2000
vim.opt.whichkeydelay
set whichkeydelay
Delay in milliseconds before the popup appears. Subsequent keystrokes update the popup instantly.
Which-key group labels
Name groups by their full key prefix. Use the leader character + prefix for leader groups (e.g., \t for table), or a raw prefix for non-leader groups (e.g., cs for surround changes). The UI provides a list of existing labels with the ability to add new ones or delete custom entries. Built-in features register default labels that your entries can override.
Which-key command labels
Describe individual bindings in the which-key popup. The UI shows a list of all active bindings (including those from vimrc) and allows you to provide a custom label for each. Entries set in vimrc appear as read-only rows.
Advanced
Name
Type
Default
Range/Options
Lua
Vimrc
Description
Scrolloff lines
number
5
0–9999
vim.opt.scrolloff
set scrolloff
Number of lines to keep visible above and below when scrolling.
Multi-line text object scan range
slider
20
5–200
vim.opt.scanlimit
set scanlimit
Maximum lines to scan in each direction for multi-line text objects.
Tip
Set Scrolloff lines to 9999 to keep the cursor vertically centered.
Picker
Fuzzy picker configuration, external grep, and bundled picker sources for popular community plugins. Sources register automatically when the target plugin is detected and unregister when it is disabled.
Name
Type
Default
Description
Omnisearch
toggle
true
Register Omnisearch as a picker source for full-text vault search.
Obsidian Tasks
toggle
true
Register Obsidian Tasks as a picker source for navigating tasks.
Dataview
toggle
true
Register Dataview as a picker source for browsing indexed pages.
Input method
Name
Type
Default
Range/Options
Description
Enable input method switching
toggle
false
Automatically switch input methods when entering/leaving insert mode. Per-view state across all editor views (split panes, popovers, canvas cards). Desktop only.
Auto-fill binary path and arguments for common IM tools. Values are editable after selection.
IM binary path
text
Absolute path to the IM switching binary (e.g., /opt/homebrew/bin/macism, /usr/bin/fcitx5-remote). Supports ~.
Obtain IM arguments
text
Arguments to query the current IM. Empty for macism/im-select. -n for fcitx5-remote.
Switch IM arguments
text
{im}
Arguments to switch IM. Use {im} as placeholder. -s {im} for fcitx5-remote. engine {im} for ibus.
Normal mode IM
text
IM identifier to switch to in normal mode (e.g., com.apple.keylayout.ABC, keyboard-us, 1033).
Insert mode IM behavior
dropdown
restore
Restore previous IM, Use fixed default IM
Restore: switch back to the IM before leaving insert. Default: always switch to a fixed IM.
Default insert mode IM
text
IM identifier for insert mode (only when behavior is “Use fixed default IM”).
Tip
The Lua API vim.obsidian.im provides programmatic control. Set vim.obsidian.im.auto = false in your init.lua to disable auto-wiring and handle switching entirely via autocmds.
Settings not available via vimrc
Configuration mode (configMode): Cannot be set via vimrc or init.lua because it controls which config files are loaded (circular dependency).
Hint mode global hotkey (hintModeHotkey): Requires a specialized recording UI to capture modifier keys and cannot be easily represented as a simple string in a vimrc file.
Leader key bindings (leaderBindings): While the plugin provides a UI for this, the same functionality is already achievable via standard nmap <leader>... commands in your vimrc.
Fuzzy picker for buffers (picker): Currently only configurable in settings.
Picker leader mappings (pickerLeaderMappings): Currently only configurable in settings.
Picker matching engine (pickerMatcherEngine): Currently only configurable in settings. Default is ufuzzy (fast pure-JS matcher with filename-aware ranking). obsidian uses Obsidian’s built-in prepareFuzzySearch API (zero bundle cost, maintained by Obsidian).