visual.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarVisual modeVisualVisual-modevisual-modeVisual modeisa flexible andeasy way to selecta piece of text for anoperator. Itis the only way to selecta block of text.Thisis introduced insection04.4 of the user manual.1. UsingVisual modevisual-use2. Starting and stoppingVisual modevisual-start3. Changing theVisual areavisual-change4. Operating on theVisual areavisual-operators5. Blockwise operatorsblockwise-operators6. Repeatingvisual-repeat7. Examplesvisual-examples8.Select modeSelect-mode{Since Vim 7.4.200 the |+visual| feature is always included}==============================================================================1. UsingVisual modevisual-useUsingVisual mode consists of three parts:1.Mark the start of the text with "v", "V" orCTRL-V. The character under the cursor will be usedas the start.2. Move to theend of the text. The text from the start of theVisual mode up to and including the character under the cursoris highlighted.3. Type anoperator command. The highlighted characters will be operated upon.The'highlight' option can be used to set the display mode to use forhighlighting inVisual mode.The'virtualedit' option can be used to allow positioning the cursor topositions where thereis no actual character.The highlighted text normally includes the character under the cursor.However, when the'selection' optionis set to "exclusive" and the cursorisafter theVisual area, the character under the cursoris not included.With "v" the text before the start position and after theend position willnot be highlighted. However, alluppercase and non-alpha operators, except"~" and "U", will work on whole lines anyway. See thelist of operatorsbelow.visual-blockWithCTRL-V (blockwiseVisual mode) the highlighted text will bea rectanglebetween start position and the cursor. However, some operators work on wholelines anyway (see thelist below). The change and substitute operators willdelete the highlighted text and then start insertionat the top leftposition.==============================================================================2. Starting and stoppingVisual modevisual-startvcharacterwise-visual[count]vStartVisual mode per character.With[count] select the same number of characters orlinesas used for the lastVisual operation, butatthe current cursor position, multiplied by[count].When the previousVisual operation was ona block boththe width and height of the block are multiplied by[count].When there was no previousVisual operation[count]characters are selected. Thisis like moving thecursor rightN *[count] characters. Oneless when'selection'is not "exclusive".Vlinewise-visual[count]VStartVisual mode linewise.With[count] select the same number of linesas usedfor the lastVisual operation, butat the currentcursor position, multiplied by[count]. When therewas no previousVisual operation[count] lines areselected.CTRL-Vblockwise-visual[count]CTRL-VStartVisual mode blockwise.Note: Under WindowsCTRL-V could be mapped to paste text,it doesn't workto startVisual mode then, seeCTRL-V-alternative.[count]is usedas withv above.If you use<Esc>, click the left mouse button or use any command thatdoesa jump to another buffer while inVisual mode, the highlighting stopsand no textis affected. Also when you hit "v" incharacterwiseVisual mode,"CTRL-V" in blockwiseVisual mode or "V" inlinewiseVisual mode. If you hitCTRL-Z the highlighting stops and the editoris suspended ora new shellisstartedCTRL-Z. new mode after typing:v_vv_CTRL-Vv_Vold mode "v" "CTRL-V" "V"NormalVisual blockwiseVisuallinewiseVisualVisualNormal blockwiseVisuallinewiseVisualblockwiseVisualVisualNormallinewiseVisuallinewiseVisualVisual blockwiseVisualNormalgvv_gvreselect-VisualgvStartVisual mode with the same areaas the previousarea and the same mode.InVisual mode the current and the previousVisualarea are exchanged.After using "p" or "P" inVisual mode the text thatwasput will be selected.gnv_gngnSearch forward for the last used search pattern, likewithn, and startVisual mode to select the match.If the cursoris on the match, visually selects it.If anoperatoris pending, operates on the match.E.g., "dgn" deletes the text of the next match.IfVisual modeis active,extends the selectionuntil theend of the next match.'wrapscan' applies.Note: Unliken the search direction does not dependon the previous search command.gNv_gNgNLikegn but searches backward, like withN.<LeftMouse><LeftMouse>Set the current cursor position. IfVisual modeisactiveitis stopped. Only when'mouse' optioncontains 'n' or 'a'. If the positionis within'so'lines from the last line on the screen the textisscrolled up. If the positionis within'so' linesfrom the first line on the screen the textis scrolleddown.<RightMouse><RightMouse>StartVisual mode ifitis not active. The text fromthe cursor position to the position of the clickishighlighted. IfVisual mode was already active movethe start orend of the highlighted text, whicheveris closest, to the position of the click. Only when'mouse' option contains 'n' or 'a'.Note: when'mousemodel'is set to "popup",<S-LeftMouse> has to be used instead of<RightMouse>.<LeftRelease><LeftRelease>This works likea<LeftMouse>, ifitis notatthe same positionas<LeftMouse>. In an older versionof xterm you won't see the selected area until thebuttonis released, unless thereis access to thedisplay where the xtermis running (via the DISPLAYenvironment variable or the-display argument). Onlywhen'mouse' option contains 'n' or 'a'.<LeftMouseNM>Internal mouse code, used for clicking on the status<LeftReleaseNM>line to focusa window. NM stands for non-mappable.You cannot use these, but they might show up in someplaces.IfVisual modeis not active and the "v", "V" orCTRL-Vis preceded withacount, the size of the previously highlighted areais used fora start. Youcan then move theend of the highlighted area and give an operator. The typeof the old areais used (character, line or blockwise).- LinewiseVisual mode: The number of linesis multiplied with the count.- BlockwiseVisual mode: The number of lines and columnsis multiplied with the count.-NormalVisual mode within one line: The number of charactersis multiplied with the count.-NormalVisual mode with several lines: The number of linesis multiplied with the count, in the last line the same number of charactersis usedas in the last line in the previously highlighted area.The start of the textis the Cursor position. If the "$" command was usedasone of the last commands to extend the highlighted text, the area will beextended to the rightmost column of the longest line.If you want to highlight exactly the same areaas the last time, you can use"gv"gvv_gv.v_<Esc><Esc>InVisual mode: StopVisual mode.v_CTRL-CCTRL-CInVisual mode: StopVisual mode. Wheninsert modeispending (the mode message shows"-- (insert) VISUAL--"),itis also stopped.On MS-Windows, you may need to pressCTRL-Breakdos-CTRL-Break.==============================================================================3. Changing theVisual areavisual-changev_ooGo to Otherend of highlighted text: The currentcursor position becomes the start of the highlightedtext and the cursoris moved to the otherend of thehighlighted text. The highlighted area remains thesame.v_OOGo to Otherend of highlighted text. Thisis like"o", but inVisual block mode the cursor moves to theother corner in the same line. When the cornerisata character that occupies more than one position onthe screen (e.g.,a<Tab>), the highlighted text maychange.v_$When the "$" commandis used with blockwiseVisual mode, the rightend of thehighlighted text will be determined by the longest highlighted line. Thisstops whena motion commandis used that does not move straight up or down.For moving theend of the block many commands can be used, but you cannotuseEx commands, commands that make changes orabandon the file. Commands(starting with) ".", "&",CTRL-^, "Z",CTRL-],CTRL-T,CTRL-R,CTRL-IandCTRL-O causeabeep andVisual mode continues.When switching to anotherwindow on the same buffer, the cursor position inthatwindowis adjusted, so that the sameVisual areais still selected. Thisis especially useful toview the start of theVisual area in one window, andtheend in another. You can then use<RightMouse> (or<S-LeftMouse> when'mousemodel'is "popup") to drag eitherend of theVisual area.==============================================================================4. Operating on theVisual areavisual-operatorsThe operators that can be used are:~switchcasev_~ddeletev_dcchange (4)v_cyyankv_y>shift right (4)v_><shift left (4)v_<!filter through external command (1)v_!=filter through'equalprg' option command (1)v_=gqformat lines to'textwidth' length (1)v_gqTheobjects that can be used are:awaword (with white space)v_awiwinnerwordv_iwaWaWORD (with white space)v_aWiWinnerWORDv_iWasasentence (with white space)v_asisinnersentencev_isapaparagraph (with white space)v_apipinnerparagraphv_ipaba () block (with parentheses)v_abibinner () blockv_ibaBa{} block (with braces)v_aBiBinner{} blockv_iBata<tag> </tag> block (with tags)v_atitinner<tag> </tag> blockv_ita<a<> block (with <>)v_a<i<inner<> blockv_i<a[a[] block (with [])v_a[i[inner[] blockv_i[a"a double quotedstring (with quotes)v_aquotei"inner double quotedstringv_iquotea'a single quotedstring (with quotes)v_a'i'inner simple quotedstringv_i'a`astring in backticks (with backticks)v_a`i`innerstring in backticksv_i`Additionally the following commands can be used::startEx command for highlighted lines (1)v_:rchange (4)v_rschangev_sCchange (2)(4)v_CSchange (2)v_SRchange (2)v_Rxdeletev_xDdelete (3)v_DXdelete (2)v_XYyank (2)v_Ypputv_pPput without overwritingregistersv_PJjoin (1)v_JUmakeuppercasev_Uumakelowercasev_u^]findtagv_CTRL-]Iblockinsertv_b_IAblock appendv_b_A(1): Always whole lines, see:visual_example.(2): Whole lines when not usingCTRL-V.(3): Whole lines when not usingCTRL-V, delete until theend of the line when usingCTRL-V.(4): When usingCTRL-V operates on the block only.Note that the ":vmap" command can be used to specifically map keys inVisualmode. For example, if you would like the "/" command not to extend theVisualarea, but instead take the highlighted text and search for that::vmap / y/<C-R>"<CR>(In the<>notation<>, when typingit you should typeit literally; youneed to remove the 'B' and '<' flags from'cpoptions'.)If you want to givea register name using the """ command,do this just beforetyping theoperator character: "v{move-around}"xd".If you want to giveacount to the command,do this just before typing theoperator character: "v{move-around}3>" (move lines 3 indents to the right).{move-around}The{move-around}is any sequence ofmovement commands.Note the differencewith{motion}, whichis only ONEmovement command.Another way to operate on theVisual areais using the/\%V item inapattern. For example, to replace all '(' in theVisual area with '#'::'<,'>s/\%V(/#/gNote that the "'<,'>" will appear automatically when you press ":" inVisualmode.==============================================================================5. Blockwise operatorsblockwise-operatorsReminder: Use'virtualedit' to be able to select blocks that start orendafter theend ofa line or halfwaya tab.Visual-blockInsertv_b_IWitha blockwise selection, I{string}<ESC> willinsert{string}at the startof block on every line of the block, provided that the lineextends into theblock. Thus lines that are short will remain unmodified. TABs are split toretain visual columns. Works only for adding text toa line, not fordeletions. Seev_b_I_example.Visual-block Appendv_b_AWitha blockwise selection, A{string}<ESC> will append{string} to theend ofblock on every line of the block. Thereis some differing behavior where theblock RHSis not straight, due to different line lengths:1. Block was created with<C-v>$ In thiscase thestringis appended to theend of each line.2. Block was created with<C-v>{move-around} In thiscase thestringis appended to theend of the block on each line, andwhitespaceis inserted to pad to the end-of-block column.Seev_b_A_example.Note: "I" and "A" behave differently for lines that don't extend into theselected block. This was done intentionally, so that you candoit the wayyou want.Works only for adding text toa line, not for deletions.Visual-block changev_b_cAll selected text in the block will be replaced by the same text string. Whenusing "c" the selected textis deleted andInsert mode started. You can thenenter text (withouta line break). When you hit<Esc>, the samestringisinserted in all previously selected lines.Visual-block Changev_b_CLike using "c", but the selectionis extended until theend of the line forall lines.v_b_<Visual-block Shiftv_b_>The blockis shifted by'shiftwidth'. The RHS of the blockis irrelevant.The LHS of the block determines the point from which to applya right shift,and padding includes TABs optimally according to'ts' and'et'. The LHS ofthe block determines the point up to which toshift left.Seev_b_>_example.Seev_b_<_example.Visual-blockReplacev_b_rEvery screen char in the highlighted regionis replaced with the same char, ieTABs are split and the virtualwhitespaceis replaced, maintaining screenlayout.Seev_b_r_example.==============================================================================6. Repeatingvisual-repeatWhenrepeatingaVisual mode operator, theoperator will be applied to thesame amount of textas the last time:- LinewiseVisual mode: The same number of lines.- BlockwiseVisual mode: The same number of lines and columns.-NormalVisual mode within one line: The same number of characters.-NormalVisual mode with several lines: The same number of lines, in the last line the same number of charactersas in the last line the last time.The start of the textis the Cursor position. If the "$" command was usedasone of the last commands to extend the highlighted text, therepeating willbe applied up to the rightmost column of the longest line. Anycount passedto the. commandis not used.==============================================================================7. Examplesvisual-examples:visual_exampleCurrently the ":" command works on whole lines only. When you select part ofa line, doing something like ":!date" will replace the whole line. If youwant only part of the line to be replaced you will have to makeamapping forit. Ina future release ":" may work onpartial lines.Hereis an example, to replace the selected text with the output of "date"::vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kgJgJ(In the<>notation<>, when typingit you should typeit literally; youneed to remove the 'B' and '<' flags from'cpoptions')What this does is:<Esc>stopVisual mode`>go to theend of theVisual areaa<CR><Esc>break the line after theVisual area`<jump to the start of theVisual areai<CR><Esc>break the line before theVisual area!!date<CR>filter theVisual text through datekJJJoin the lines back togethervisual-searchHereis an idea foramapping that makesit possible todoa search for theselected text::vmap X y/<C-R>"<CR>(In the<>notation<>, when typingit you should typeit literally; youneed to remove the 'B' and '<' flags from'cpoptions')Note that special characters (like '.' and'*') will cause problems.Visual-block Examplesblockwise-examplesWith the following text,I will indicate the commands to produce the block andthe results below. In all cases, the cursor begins on the 'a' in the firstline of the test text.The followingmodeline settings are assumed ":ts=8:sw=4:".It will be helpful to:set hls/<TAB>where<TAB>isa real TAB. This helps visualise the operations.The test text is:abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdef ghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz1. fo<C-v>3jISTRING<ESC>v_b_I_exampleabcdefghijklmnSTRINGopqrstuvwxyzabc STRING defghijklmnopqrstuvwxyzabcdef ghi STRING jklmnopqrstuvwxyzabcdefghijklmnSTRINGopqrstuvwxyz2. fo<C-v>3j$ASTRING<ESC>v_b_A_exampleabcdefghijklmnopqrstuvwxyzSTRINGabcdefghijklmnopqrstuvwxyzSTRINGabcdef ghijklmnopqrstuvwxyzSTRINGabcdefghijklmnopqrstuvwxyzSTRING3. fo<C-v>3j3l<..v_b_<_exampleabcdefghijklmnopqrstuvwxyzabc defghijklmnopqrstuvwxyzabcdef ghi jklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz4. fo<C-v>3j>..v_b_>_exampleabcdefghijklmn opqrstuvwxyzabc defghijklmnopqrstuvwxyzabcdef ghi jklmnopqrstuvwxyzabcdefghijklmn opqrstuvwxyz5. fo<C-v>5l3jrXv_b_r_exampleabcdefghijklmnXXXXXXuvwxyzabc XXXXXXhijklmnopqrstuvwxyzabcdef ghi XXXXXX jklmnopqrstuvwxyzabcdefghijklmnXXXXXXuvwxyz==============================================================================8.Select modeSelectSelect-modeSelect mode looks likeVisual mode, but the commands accepted are quitedifferent. This resembles the selection mode in Microsoft Windows.When the'showmode' optionis set, "-- SELECT--"is shown in the last line.EnteringSelect mode:- Using the mouse to select an area, and'selectmode' contains "mouse".'mouse'must also containa flag for the current mode.- Usinga non-printablemovement command, with the Shift key pressed, and'selectmode' contains "key". For example:<S-Left> and<S-End>.'keymodel'must also contain "startsel".- Using "v", "V" orCTRL-V command, and'selectmode' contains "cmd".- Using "gh", "gH" or "g_CTRL-H" command inNormal mode.- FromVisual mode, pressCTRL-G.v_CTRL-GCommands inSelect mode:- Printable characters,<NL> and<CR> cause the selection to be deleted, and Vim entersInsert mode. The typed characteris inserted.- Non-printablemovement commands, with the Shift key pressed, extend the selection.'keymodel'must include "startsel".- Non-printablemovement commands, with the Shift key NOT pressed, stopSelect mode.'keymodel'must include "stopsel".- ESC stopsSelect mode.-CTRL-O switches toVisual mode for the duration of one command.v_CTRL-O-CTRL-G switches toVisual mode.-CTRL-R{register} selects the register to be used for the text thatis deleted when typing text.v_CTRL-R Unless you specify the "_" (black hole) register, the unnamed registeris also overwritten.Otherwise, typed characters are handledas inVisual mode.When using anoperator inSelect mode, and the selectionis linewise, theselected lines are operated upon, but like incharacterwise selection. Forexample, whena whole lineis deleted,it can later be pasted halfwaya line.Mappings andmenus inSelect mode.Select-mode-mappingWhen mappings andmenus are defined with the:vmap or:vmenu command theywork both inVisual mode and inSelect mode. When these are used inSelectmode Vim automatically switches toVisual mode, so that the same behaviorasinVisual modeis effective. If you don't want this use:xmap or:smap.One particular edge case::vnoremap <C-K> <Esc>This endsVisual mode when inVisual mode, but inSelect modeit does notwork, becauseSelect modeis restored after executing the mapped keys. Youneed to use::snoremap <C-K> <Esc>Users will expect printable characters to replace the selected area.Therefore avoidmapping printable characters inSelect mode. Or use:sunmap after:map and:vmap to removeit forSelect mode.After themapping or menu finishes, the selectionis enabled again andSelectmode entered, unless the selected area was deleted, another buffer becamethe current one or thewindow layout was changed.Whena character was typed that causes the selection to be deleted andInsertmode started,Insert mode mappings are applied to this character. This maycause some confusion, becauseit meansInsert mode mappings apply toacharacter typed inSelect mode. Language mappings applyas well.gVv_gVgVAvoid the automatic reselection of theVisual areaafteraSelect modemapping or menu has finished.Put this just before theend of themapping or menu.At leastit should be after any operations on theselection.ghghStartSelect mode, characterwise. Thisis like "v",but startsSelect mode instead ofVisual mode.Mnemonic: "get highlighted".gHgHStartSelect mode, linewise. Thisis like "V",but startsSelect mode instead ofVisual mode.Mnemonic: "get Highlighted".g_CTRL-HgCTRL-HStartSelect mode, blockwise. Thisis likeCTRL-V,but startsSelect mode instead ofVisual mode.Mnemonic: "get Highlighted". vim:tw=78:ts=8:noet:ft=help:norl: