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 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
  • 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.

🔧 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