VimNav Documentation

Complete guide to vim-style browser navigation with keyboard shortcuts, advanced features, and configuration options.

Getting Started Navigation Quick Nav Modes VimEdit Commands Configuration Keybinds Theme Options Advanced

Quick Reference

Press ? anytime in VimNav to see the help overlay with all keybindings.

🚀 Getting Started

Installation

VimNav is available as a Chrome extension. Follow these steps to get started:

  1. Install VimNav from the Chrome Web Store
  2. Pin the extension to your toolbar for easy access
  3. Visit any webpage and start using vim keybindings immediately
Note: VimNav works on all websites and requires no additional setup or configuration.

First Steps

Once installed, VimNav is immediately active on all web pages. Try these basic commands:

? Show the help overlay with all keybindings
jk Scroll down and up on any page
e Open the tab navigator overlay
o Open the url search for quick navigation to new urls, history or search
f Enter hint mode to click links with keyboard

Basic Usage Patterns

VimNav follows vim's modal philosophy. You're always in one of several modes:

  • Normal Mode - Default mode for navigation and commands
  • Insert Mode - For typing in form fields (enters automatically)
  • Visual Mode - For text selection and manipulation
  • Hint Mode - For keyboard-only link clicking

🌐 Quick Navigation

Instantly navigate to URLs, search engines, or browse history with the URL search overlay.

o Open URL search overlay for quick navigation

Navigation Features

The URL search overlay provides multiple navigation options:

  • Direct URLs - Type any URL to navigate directly (auto-adds https://)
  • Search Engines - Type search terms to search with your default search engine
  • History Search - Searches your browser history as you type
  • Bookmarks - Finds matching bookmarks in your browser
  • Smart Suggestions - Provides intelligent suggestions based on your input

Navigation Controls

jk
Navigate up/down through URL suggestions
Enter
Navigate to selected URL or search term
Ctrl+Enter
Open selected URL in new tab
Esc
Close URL search overlay
Pro Tips:
  • Use search terms without domain type strings to search with your default engine
  • History results show page titles and URLs for easy identification

🔄 Mode System

VimNav uses vim's modal system for different types of interaction.

Normal Mode

The default mode for navigation and commands. Most keybindings work in normal mode.

Esc Always returns you to normal mode from any other mode
EscEsc Focus main body for reliable vim navigation

Insert Mode

Automatically activated when you focus input fields, text areas, or contenteditable elements.

i Manually enter insert mode (finds nearest input)
Esc Exit insert mode and return to normal mode

Visual Mode

Select and manipulate text elements on the page. See the Visual Mode section for details.

Hint Mode

Click links and interactive elements using keyboard hints. See the Hint Mode section for details.

📝 VimEdit Mode

VimNav includes a powerful VimEdit feature that opens a full vim editor for any input field on web pages. This allows you to edit form fields, text areas, and contenteditable elements using vim's complete editing capabilities.

Entering VimEdit Mode

Ctrl+i Activate input field selection with visual hints
a-z Type hint letters to select the desired input field
Enter Confirm selection when multiple fields match

The VimEdit Interface

Once a field is selected, VimEdit opens with:

  • Full vim modal interface with transparent overlay
  • Line numbers for multi-line editing
  • Color-coded status bar showing current mode and cursor position
  • Command line for vim commands (:w, :q, etc.)
  • Visual mode indicators with distinct colors for different selection types

Vim Modes in VimEdit

Normal Mode (Default)

Standard vim navigation and text manipulation:

Movement
hjkl
Character/line movement
wbe
Word movement (treats punctuation as separate words)
WBE
WORD movement (treats non-whitespace as single words)
0$
Line start/end
ggG
File start/end
f{char}F{char}
Find character
Editing
xX
Delete character
dd
Delete line
yy
Yank (copy) entire line
pP
Paste (line-based or character-based)
dwcwyw
Word operations (small words)
uCtrl+r
Undo/Redo last change
Mode Transitions
i Insert mode at cursor
a Insert after cursor
oO Open new line below/above
v Visual mode
V Visual line mode

Insert Mode

Standard text insertion with vim keybindings:

Esc Return to normal mode
BackspaceDelete Character deletion
Enter New line
Tab Insert spaces (configurable)

Visual Mode

Text selection and manipulation with enhanced visual feedback:

Character Visual Mode (v)
Blue highlighting Precise character-level selection
Movement keys Extend selection character by character
Line Visual Mode (V)
Orange highlighting Full-line selection
Movement keys Extend selection line by line
Operations
dx Delete selection
y Yank selection
c Change selection (delete and enter insert mode)

Command Mode

Vim command-line interface:

: Enter command mode
:w Save changes to input field
:q Quit VimEdit
:wq Save and quit
:q! Quit without saving

Mode Indicators

VimEdit provides visual feedback through color-coded indicators:

Status Bar Mode Colors

-- NORMAL -- Gray-blue background (#565f89)
-- INSERT -- Green background (#9ece6a)
-- VISUAL -- Purple background (#bb9af7)
-- REPLACE -- Red-pink background (#f7768e)

Visual Selection Colors

Blue highlighting Character visual mode (v) for precise selection
Orange highlighting Line visual mode (V) for full-line selection

Smart Clipboard System

VimEdit automatically detects whether clipboard content should be pasted as lines or characters:

Line-based Operations

yyddcc Commands that yank entire lines
p Paste line below current line
P Paste line above current line

Character-based Operations

ywy$df{char} Commands that yank character ranges
p Paste after cursor position
P Paste before cursor position

Usage Examples

Basic Form Editing

  1. Navigate to any web form
  2. Press Ctrl+i to see input field hints
  3. Type the hint letter (e.g., a) to select first field
  4. Edit using vim commands:
    • i to start typing
    • Esc to return to normal mode
    • :wq to save and close

Advanced Text Manipulation

Example workflow:
  1. Ctrl+i → b (Select field with hint 'b')
  2. gg (Go to start)
  3. dw (Delete first word)
  4. u (Undo deletion)
  5. d3w (Delete 3 words)
  6. Ctrl+r (Redo)
  7. A (Insert at end of line)
  8. :wq (Save and exit)
Pro Tips:
  • Use w/e for precise punctuation handling, W/E for speed
  • df{char} includes the character, dt{char} excludes it
  • Blue highlighting for character selection, orange for line selection
  • Ctrl+I toggles maximize mode for distraction-free editing

📑 Tab Management

VimNav provides powerful tab navigation and management inspired by NERDTree.

Opening Tab Navigator

e Toggle tabs overlay - shows all open tabs in current window
Ctrl+P Telescope-style tab search (Chrome shortcut integration)

Tab Navigation

When the tabs overlay is open:

jk
Navigate tabs up/down
gg
Jump to first tab
G
Jump to last tab
Enter
Switch to selected tab
o
Expand all tab groups
c
Collapse all tab groups
hl
Collapse/expand focused group (persists)
xd
Close selected tab
/
Focus tab search input

Use move mode to reposition tabs without leaving the overlay.

m Enter move mode for the highlighted tab
jk Select the destination tab or group while moving
P Toggle before/after placement relative to the target
Enter Confirm the move (tab stays highlighted in its new spot)
Esc Cancel move mode and restore the original position

Grouped tabs respect the destination group’s expansion state, and VimNav preserves your scroll position while the list refreshes so you never lose context.

Tab Actions

r Reload selected tab
a Show tab group editor for organizing tabs
Esc Close tabs overlay and return to normal mode
Tip: The help overlay (?) and keyboard reference tables now surface the move mode and group control keys directly above the tabs overlay shortcuts.

🎯 Hint Mode

Click links, buttons, and interactive elements without using the mouse.

Using Hint Mode

f Enter hint mode - shows letter hints on clickable elements
a-z Type hint characters to narrow down selection
Enter Click the selected element
Backspace Delete last character or exit hint mode
Esc Exit hint mode without clicking

Hint Targets

Hint mode automatically detects and highlights:

  • Links (<a> elements)
  • Buttons (<button> elements)
  • Form inputs (input, select, textarea)
  • Clickable elements with click handlers
  • Elements with role="button" or tabindex
Tip: Hint characters are case-insensitive. Type partial hints to filter - you don't always need to complete the full hint sequence.

👁️ Visual Mode

Select and manipulate text content on web pages using vim-style text selection.

Entering Visual Mode

v Enter visual mode - shows hints on text elements
a-z Type hint to select a text element for manipulation
Enter Start text selection within the chosen element

Text Selection

Once you've selected an element and entered text selection mode:

hl
Extend selection left/right by character
jk
Extend selection down/up by line
wb
Extend selection by word forward/backward
gg
Extend selection to start of element
G
Extend selection to end of element

Text Operations

y Copy selected text to clipboard
Esc Exit visual mode

📍 Marks System

Create bookmarks within pages to quickly jump to specific locations.

Setting Marks

m{a-z} Set a mark at current scroll position (e.g., ma, mb, mc)

Jumping to Marks

'{a-z} Jump to the mark (e.g., 'a, 'b, 'c)
Note: Marks are page-specific and reset when you navigate to a different URL.

⌨️ Command Mode

Execute vim-style commands for advanced browser control and navigation.

Entering Command Mode

: Open command input - type commands and press Enter

Available Commands

:help Show help overlay with all keybindings
:reload Reload current page
:back Go back in browser history
:forward Go forward in browser history
:open {url} Navigate to specified URL
Tip: Commands support tab completion for faster input.

🕰️ History Search

Search and navigate through your browser history with vim-style controls.

History Navigation

H Go back in browser history
L Go forward in browser history

History Search

Use the URL search overlay (o) to search through your browser history:

  • Type keywords to search page titles and URLs
  • Navigate results with j/k
  • Press Enter to navigate to selected history item

⚙️ Extension Configuration

Customize VimNav to match your preferences and workflow across every tab and window.

Accessing Settings

Open the extension side pane by clicking on the extension icon.

You can also open Extensions → VimNav → Options or click the VimNav toolbar icon to launch the side panel configuration view.

Extension Options Overview

  • Scroll Behavior - Adjust smooth scrolling and scroll distance
  • Hint Appearance - Customize hint styling and colors
  • Theme Options - Switch between palettes or upload custom themes
  • Keybinds Editor - View, edit, and customize all keyboard shortcuts (see Keybinds Editor section)
  • Site Exclusions - Disable VimNav on specific websites
  • Search Integration - Configure default search engine

Theme Options

VimNav 1.3+ ships with refreshed built-in palettes and the ability to import custom iTerm2 color schemes. The active theme instantly recolors overlays, the side panel, and the options UI with no page refresh required.

Selecting Themes

The side panel exposes a `Theme List` that mirrors the options page. Single-clicking a palette (or selecting its radio control) applies it immediately and syncs the active colors across every open tab and window. The help overlay (?) now reflects the currently selected palette so the keyboard reference always matches what you see.

Uploading Custom Themes

Use the `Upload Theme` button in the side panel to import a .itermcolors file. After choosing a file, VimNav validates and stores the theme before adding it to the list.

  • Max file size: 200 KB
  • Format: Valid iTerm2 XML; malformed files surface an error toast
  • Storage: Free tier keeps up to two custom themes at a time; delete one to upload another

Themes adopt the embedded display name when available, otherwise VimNav falls back to the filename. Each upload persists its metadata (timestamp, source type) so you can audit when palettes were added.

Persistence & Sync

  • Theme data is stored in chrome.storage.local and restored automatically when Chrome reopens.
  • Background, content, and side panel contexts listen for storage and runtime events to broadcast changes instantly.
  • Any active overlays update in place, keeping scroll position and focus while colors transition.

Removing Themes & Fallback

  • Deleting the active custom theme automatically falls back to the VimNav default palette.
  • The `Delete` button is disabled for built-in themes; custom themes prompt you to confirm removal to prevent accidental loss.
  • Once removed, the theme disappears from both the options page and side panel lists within the same sync cycle.

⌨️ Keybinds Editor

VimNav includes a built-in keymap editor that allows you to view, edit, and customize all keyboard shortcuts. The editor uses a Vim-inspired keymap system with modal editing (Normal, Insert, Visual modes) and context-specific bindings (overlays, states). All keybindings are fully customizable and changes take effect immediately—no page reload required.

Quick Start: Open command palette with :, type :keybinds, press Enter. Navigate with j/k, press Enter to edit, a to add, d to delete. Press x to export your keymap as backup.

Accessing the Editor

Open the keymap editor using one of these methods:

: Open command palette
keybinds Type the keybinds command

You can also bind a custom key to the keymap-editor.open command.

Editor Interface

The editor features a three-tab interface:

  • Bindings Tab - Browse, search, and edit all keybindings
  • Info Tab - View keymap metadata, warnings, and conflict detection
  • Docs Tab - Quick reference for the keymap system

Viewing Keybindings

Keybindings are displayed using this DSL format:

DSL Format
<keys> → <command> (<modes>, <contexts>) "description"

Examples

Common Keybinding Patterns
j → scroll.down (n, root) "Scroll down" <C-f> → scroll.pageDown (n, root) "Page down" g g → scroll.top (n, root) "Scroll to top" <CR> → tabs.activate (n, tabs-overlay) "Activate selected tab"

Navigation Keys

j / k Move down/up through bindings
g g / G Jump to first/last binding
/ Focus search input to filter bindings
Ctrl+h / Ctrl+l Switch between tabs

Editing Keybindings

To edit an existing keybinding:

  1. Navigate to a binding with j/k or search with /
  2. Press Enter to enter edit mode
  3. Modify the Keys field (e.g., change j to <C-j>)
  4. Update the Description field if desired
  5. Press Enter to save or Escape to cancel
Note: Command, modes, and contexts are read-only during editing. To change these, delete the binding and recreate it with the desired values.

Context-Aware Escape Behavior

  • While editing: Cancels edit, returns to browse mode (editor stays open)
  • While browsing: Closes the entire editor

Adding New Keybindings

To add a new keybinding:

  1. Navigate to where you want to insert the binding
  2. Press a to add a new binding
  3. Fill in all required fields in the DSL format:
<C-d> → scroll.halfPageDown (n, root) "Scroll half page down"
  1. Press Enter to save

Key Notation Reference

<C-x>
Ctrl + x
<A-x>
Alt + x
<S-x>
Shift + x
<M-x>
Meta (Cmd) + x
<Space>
Space bar
<CR>
Enter/Return
<Esc>
Escape
<BS>
Backspace
<Tab>
Tab
g g
Multi-key sequence

Deleting Keybindings

To delete a keybinding:

  1. Navigate to the binding you want to remove
  2. Press d
  3. Confirm the deletion when prompted

Deleted bindings are removed immediately and persist across sessions.

Conflict Detection

VimNav automatically detects conflicting keybindings. Conflicts are indicated with badges showing ⚠️ N where N is the number of conflicts.

Example Conflicts

Conflicting Keybindings
<Space> → scroll.pageDown (n, root) ⚠️ 1 <Space> → scroll.bottom (n, root) ⚠️ 1

Hovering over a conflict badge shows details: "Conflicts with 1 other binding(s): scroll.bottom"

Note: If conflicts remain, the last binding loaded wins at runtime.

Resolving Conflicts

  1. Navigate to the conflicting binding
  2. Press Enter to edit
  3. Change keys to something unique
  4. Press Enter to save
  5. Conflict warning disappears

Exporting Keymaps

To export your current keymap:

  1. Press x from any tab in the editor
  2. File vimnav-keymap.json downloads automatically
  3. JSON contains all current keybindings with metadata

Export Use Cases

  • Backup before making major changes
  • Share custom keymaps with others
  • Edit manually in a text editor
  • Version control your configuration

Importing Keymaps

To import a keymap:

  1. Press i from any tab in the editor
  2. Select a valid JSON keymap file
  3. File is validated and loaded immediately
  4. Invalid files show error toast with details
Warning: Import replaces the entire current keymap. Export first as backup!

Validation Errors

Import may fail due to:

  • Invalid JSON syntax
  • Missing required fields (keys, command, modes)
  • Unknown modes or contexts
  • Malformed key notation

Resetting to Defaults

To reset all keybindings to defaults:

  1. Press R from the keymap editor
  2. Confirm the reset action
  3. All custom bindings are cleared
  4. Default VimNav keymap is restored
Warning: This action cannot be undone. Export your keymap first!

Modes and Contexts

Vim-Style Modes

  • n - Normal mode (default navigation mode)
  • i - Insert mode (when typing in input fields)
  • v - Visual mode (text selection)

Common Contexts

  • root - Base page navigation
  • tabs-overlay - Tabs overlay
  • hint - Hint overlay (link navigation)
  • keymap-editor - Keymap editor itself
  • command-palette - Command palette
  • input-select - Input selector overlay

Context-specific bindings only work when that context is active (e.g., tabs-overlay bindings only work when tabs overlay is open).

Command Categories

VimNav uses a category.action naming pattern for consistency:

  • scroll.* - Page scrolling (scroll.down, scroll.pageUp, scroll.top)
  • tabs.* - Tab management (tabs.open, tabs.navigateDown, tabs.activate)
  • hint.* - Link navigation (hint.open, hint.click)
  • history.* - Browser history (history.back, history.forward)
  • mode.* - Mode switching (mode.insert, mode.visual)
  • marks.* - Marks system (marks.startCreate, marks.startNavigate)
  • search.* - In-page search (search.start, search.next)

Persistence & Sync

  • VimNav writes keymap data to chrome.storage.local
  • Changes take effect immediately across all tabs and windows
  • Reopening Chrome restores custom keymap automatically
  • The editor itself updates live when saving changes (no need to close and reopen)

Example Customizations

Here are some common customization examples:

Make Space+G scroll to top instead of gg
<Space> g → scroll.top (n, root) "Scroll to top"
Add Ctrl+d for half-page scroll
<C-d> → scroll.halfPageDown (n, root) "Scroll half page down" <C-u> → scroll.halfPageUp (n, root) "Scroll half page up"
Create custom hint key
<Space> → hint.open (n, root) "Open hint overlay"

Best Practices

  • Export before major changes - Keep backups of working configurations
  • Test incrementally - Make one change at a time and test
  • Use consistent patterns - Follow category.action naming for custom commands
  • Be specific with descriptions - Help your future self understand each binding
  • Leverage contexts - Use context-specific bindings to avoid conflicts
  • Respect browser shortcuts - Avoid overriding critical browser keys (Ctrl+T, Ctrl+W, etc.)
  • Document your customizations - Add clear descriptions for custom bindings

Troubleshooting

Keybinding not working after edit

  • Verify the binding saved correctly (check in editor list)
  • Ensure mode is correct (n for normal page navigation)
  • Ensure context is correct (root for general page navigation)
  • Check browser console for keymap errors
  • Try reloading the page

Export/Import issues

  • Check browser console for errors
  • Ensure browser allows file downloads (export)
  • Verify JSON file is valid (import)
  • Try exporting default keymap first to see correct format

Conflict warnings

  • Last binding wins at runtime
  • Use different keys, or different modes/contexts to resolve
  • Check Info tab for full conflict report

Editor not opening

  • Ensure command palette is working (: key)
  • Check that the VimNav version is v1.4.1 or greater
  • Try reloading the extension

🔧 Settings

Detailed settings and customization options for VimNav.

General Settings

  • Enable/Disable - Toggle VimNav on/off globally
  • Scroll Speed - Adjust scrolling sensitivity
  • Smooth Scrolling - Enable/disable smooth scroll animation

Visual Settings

  • Hint Colors - Customize hint appearance
  • Overlay Themes - Choose overlay styling
  • Font Settings - Adjust font size and family for overlays

Advanced Settings

  • Debug Mode - Enable debugging features
  • Performance - Memory and performance tuning

🛠️ Troubleshooting

Common issues and solutions for VimNav.

Common Issues

VimNav Not Working

  • Check that the extension is enabled in Chrome extensions
  • Verify the site isn't in your exclusions list
  • Try pressing EscEsc to ensure focus

Keybindings Not Responding

  • Make sure you're not in an input field (press Esc)
  • Check for conflicts with other extensions
  • Try refreshing the page

Hints Not Appearing

  • Ensure there are clickable elements on the page
  • Check if the page has custom styling that hides hints
  • Try zooming out if hints are positioned incorrectly

Theme Upload Issues

  • Verify the file is a valid .itermcolors export under 200 KB—larger or malformed uploads trigger an error toast
  • If a theme does not apply immediately, open DevTools to check for storage errors and reopen the side panel or options page once storage recovers
  • Only perform a manual browser refresh if Chrome extension storage is temporarily unavailable

Getting Help

If you continue experiencing issues:

  • Visit our feedback page
  • Check the console for error messages (F12 → Console)
  • Report bugs with specific steps to reproduce