tabpage.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarEditing withwindows in multipletab pages.tab-pagetabpageThe commands which have been added to use multipletab pages are explainedhere. Additionally, there are explanations for commands that work differentlywhen used in combination with more than onetab page.1. Introductiontab-page-intro2. Commandstab-page-commands3. Other itemstab-page-other4. Setting'tabline'setting-tabline5. Setting'tabpanel'setting-tabpanel6. Setting'guitablabel'setting-guitablabel{not able to use multipletab pages when the+windows feature was disabledat compile time}{not able to usetabpanel feature when the+tabpanel feature was disabledat compile time}==============================================================================1. Introductiontab-page-introAtab page holds one or more windows. You can easily switch betweentabpages, so that you have several collections ofwindows to work on differentthings.Usually you will seealist of labelsat the top of the Vim window, one foreachtab page. With the mouse you can click on the label to jump to thattabpage. There are other ways to move betweentab pages, see below.Most commands work only in the currenttab page. That includes theCTRL-Wcommands,:windo,:all and:ball (when not using the:tab modifier).The commands that are aware of othertab pages than the current one arementioned below.Tab pages are alsoa nice way to edita buffer temporarily withoutchangingthe currentwindow layout. Opena newtab page,do whatever you want todoand close thetab page.==============================================================================2. Commandstab-page-commandsOPENINGA NEW TAB PAGE:Whenstarting Vim "vim-p filename..." opens each file argument ina separatetab page (up to'tabpagemax'). See-pA double click with the mouse in the non-GUItab pages line opensa new, emptytab page. Itis placed left of the position of the click. The first clickmay select anothertab page first, causing an extra screen update.This also works ina fewGUI versions, esp.Win32 and Motif. But only whenclicking right of the labels.In theGUItab pages line you can use the right mouse button to open menu.tabline-menu.For the relatedautocommands seetabnew-autocmd.:[count]tabe[dit]:tabe:tabedit:tabnew:[count]tabnewOpena newtab page with an empty window, after the currenttab page. If[count]is given the newtab page appears afterthetab page[count] otherwise the newtab page will appearafter the current one. :tabnew" opens tabpage after the current one :.tabnew" as above :+tabnew" opens tabpage after the next tab page" note: it is one further than :tabnew :-tabnew" opens tabpage before the current one :0tabnew" opens tabpage before the first one :$tabnew" opens tabpage after the last one:[count]tabe[dit][++opt][+cmd]{file}:[count]tabnew[++opt][+cmd]{file}Opena newtab page and edit{file}, like with:edit.For[count] see:tabnew above.:[count]tabf[ind][++opt][+cmd]{file}:tabf:tabfindOpena newtab page and edit{file} in'path', like with:find. For[count] see:tabnew above.:[count]tab{cmd}:tabExecute{cmd} and whenit opensa newwindow opena newtabpage instead. Doesn't work for:diffsplit,:diffpatch,:execute and:normal.If[count]is given the newtab page appears after thetabpage[count] otherwise the newtab page will appear after thecurrent one.Examples: :tab split " opens current buffer in new tab page :tab help gt " opens tab page with help for "gt" :.tab help gt " as above :+tab help " opens tab page with help after the next " tab page :-tab help " opens tab page with help before the " current one :0tab help " opens tab page with help before the " first one :$tab help " opens tab page with help after the last " oneCTRL-WgfOpena newtab page and edit the file name under the cursor.SeeCTRL-W_gf.CTRL-WgFOpena newtab page and edit the file name under the cursorand jump to the line number following the file name.SeeCTRL-W_gF.CLOSINGA TAB PAGE:Closing the lastwindow ofatab page closes thetab page too, unless thereisonly onetab page.Using the mouse: If thetab page lineis displayed you can click in the "X"atthe top right to close the currenttab page.A custom'tabline' may showsomething else.:tabc:tabclose:tabc[lose][!]Close currenttab page.This command fails when:- Thereis only onetab page on the screen.E784- When'hidden'is not set, [!]is not used,a buffer has changes, and thereis no otherwindow on this buffer.Changes to the buffer are not written and won't get lost, sothisisa "safe" command. :tabclose " close the current tab page:{count}tabc[lose][!]:tabc[lose][!]{count}Closetab page{count}. Fails in the same wayas:tabcloseabove. :-tabclose " close the previous tab page :+tabclose " close the next tab page :1tabclose " close the first tab page :$tabclose " close the last tab page :tabclose -2 " close the 2nd previous tab page :tabclose + " close the next tab page :tabclose 3 " close the third tab page :tabclose $ " close the last tab page :tabclose # " close the last accessed tab pageWhenatab pageis closed the nexttab page will become the current one. Thisbehaviour can be customized using the'tabclose' option.:tabo:tabonly:tabo[nly][!]Close all othertab pages.When the'hidden' optionis set, allbuffers in closedwindowsbecome hidden.When'hidden'is not set, and the'autowrite' optionis set,modifiedbuffers are written. Otherwise,windows that havebuffers that are modified are not removed, unless the [!]isgiven, then they become hidden. But modifiedbuffers arenever abandoned, so changes cannot get lost. :tabonly " close all tab pages except the current " one:{count}tabo[nly][!]:tabo[nly][!]{count}Close alltab pages except{count} one. :.tabonly " as above :-tabonly " close all tab pages except the previous " one :+tabonly " close all tab pages except the next one :1tabonly " close all tab pages except the first one :$tabonly " close all tab pages except the last one :tabonly - " close all tab pages except the previous " one :tabonly +2 " close all tab pages except the two next " one :tabonly 1 " close all tab pages except the first one :tabonly $ " close all tab pages except the last one :tabonly # " close all tab pages except the last " accessed oneSWITCHING TO ANOTHER TAB PAGE:Using the mouse: If thetab page lineis displayed you can click inatab pagelabel to switch to thattab page. Click where thereis no label togo to thenexttab page.'tabline':tabn[ext]:tabn:tabnextgt<C-PageDown>CTRL-<PageDown><C-PageDown>gti_CTRL-<PageDown>i_<C-PageDown>Go to the nexttab page. Wraps around from the last to thefirst one.:{count}tabn[ext]:tabn[ext]{count}Go totab page{count}. The firsttab page has number one. :-tabnext" go to the previous tab page :+tabnext" go to the next tab page :+2tabnext" go to the two next tab page :1tabnext" go to the first tab page :$tabnext" go to the last tab page :tabnext $" as above :tabnext #" go to the last accessed tab page :tabnext -" go to the previous tab page :tabnext -1" as above :tabnext +" go to the next tab page :tabnext +1" as above{count}<C-PageDown>{count}gtGo totab page{count}. The firsttab page has number one.:tabp[revious]:tabp:tabpreviousgT:tabN:tabN[ext]:tabNextCTRL-<PageUp><C-PageUp><C-PageUp>i_CTRL-<PageUp>i_<C-PageUp>gTGo to the previoustab page. Wraps around from the first oneto the last one.:tabp[revious]{count}:tabN[ext]{count}{count}<C-PageUp>{count}gTGo{count}tab pages back. Wraps around from the first oneto the last one.Note that the use of{count}is differentfrom:tabnext, whereitis usedas thetab page number.:tabr[ewind]:tabfir:tabfirst:tabr:tabrewind:tabfir[st]Go to the firsttab page.:tabl:tablast:tabl[ast]Go to the lasttab page.<C-Tab>g<Tab>CTRL-W_g<Tab><C-Tab>g<Tab>CTRL-Wg<Tab>Go to the last accessedtab page.Other commands::tabs:tabsList thetab pages and thewindows they contain.Showsa ">" for the current window.Showsa "+" for modified buffers.For example:Tab page 1 + tabpage.txt ex_docmd.cTab page 2> main.cREORDERING TAB PAGES::tabm[ove] [N]:tabm:tabmove:[N]tabm[ove]Move the currenttab page to aftertab page N. Use zero tomake the currenttab page the first one.Nis counted beforethe move, thus if the secondtab pageis the current one,`:tabmove 1` and `:tabmove 2` have no effect.WithoutN thetab pageis made the last one. :.tabmove" do nothing :-tabmove" move the tab page to the left :+tabmove" move the tab page to the right :0tabmove" move the tab page to the first :tabmove 0" as above :tabmove" move the tab page to the last :$tabmove" as above :tabmove $" as above :tabmove #" move the tab page after the last accessed" tab page:tabm[ove] +[N]:tabm[ove] -[N]Move the currenttab pageN places to the right (with +) or tothe left (with -). :tabmove -" move the tab page to the left :tabmove -1" as above :tabmove +" move the tab page to the right :tabmove +1" as aboveNote that althoughitis possible to moveatab page behind the N-th one byusing :Ntabmove. And moveit byN places by using :+Ntabmove. Forclarification what +N means in this context see[range].LOOPING OVER TAB PAGES::tabd:tabdo:[range]tabd[o]{cmd}Execute{cmd} in eachtab page or if[range]is given only intab pages whichtab page numberis in the[range]. It workslike doing this::tabfirst:{cmd}:tabnext:{cmd}etc.This only operates in the currentwindow of eachtab page.When an erroris detected on onetab page, furthertab pageswill not be visited.The lasttab page (or where an error occurred) becomes thecurrenttab page.{cmd} can contain'|' to concatenate several commands.{cmd}must not open or closetab pages or reorder them.Also see:windo,:argdo,:bufdo,:cdo,:ldo,:cfdoand:lfdo==============================================================================3. Other itemstab-page-othertabline-menuTheGUItab pages line hasapopup menu. Itis accessed witha right click.The entries are:CloseClose thetab page under the mouse pointer. Thecurrent one if thereis no label under the mousepointer.NewTabOpenatab page, editing an empty buffer. It appearsto the left of the mouse pointer.Open Tab...Like "NewTab" and additionally usea file selector toselecta file to edit.Diff mode works pertab page. You can see the diffs between several fileswithin onetab page. Othertab pages can show differences between otherfiles.Variables local toatab page start with "t:".tabpage-variableCurrently thereis only one option local toatab page:'cmdheight'.tabnew-autocmdTheTabLeave andTabEnterautocommand events can be used todo something whenswitching from onetab page to another. The exact order depends on what youare doing. When creatinga newtab page this worksas if you createa newwindow on the same buffer and then edit another buffer. Thus ":tabnew"triggers:WinLeaveleave currentwindowTabLeaveleave currenttab pageWinEnterenterwindow in newtab pageTabEnterenter newtab pageBufLeaveleave current bufferBufEnterenter new empty bufferWhen switching to anothertab page the order is:BufLeaveWinLeaveTabLeaveTabEnterWinEnterBufEnter==============================================================================4. Setting'tabline'setting-tablineThe'tabline' optionspecifies what the line withtab pages labels looks like.Itis only used when thereis noGUItab line.You can use the'showtabline' option to specify when you want the line withtab page labels to appear: never, when thereis more than onetab page oralways.The highlighting of thetab pages lineis set with the groups TabLineTabLineSel and TabLineFill.hl-TabLinehl-TabLineSelhl-TabLineFillA "+" will be shown foratab page that hasa modified window. The number ofwindows inatabpageis also shown. Thus "3+" means threewindows and one ofthem hasa modified buffer.An "X" (close button) will appear in the last column when multipletab pagesare open, but only if the'mouse'is enabled.The'tabline' option allows you to define your preferred way totab pageslabels. This isn't easy, thus an example will be given here.For basics see the'statusline' option. The same items can be used in the'tabline' and'tabpanel' option. Additionally, thetabpagebuflist(),tabpagenr() andtabpagewinnr()functions are useful.Since the number oftab labels will vary, you need to use anexpression forthe whole option. Something like::set tabline=%!MyTabLine()Then define the MyTabLine() function tolist all thetab pages labels.Aconvenientmethodis to splitit in two parts: Firstgo over all thetabpages and define labels for them. Then get the label for eachtab page.function MyTabLine() let s = '' for i in range(tabpagenr('$')) " select the highlighting if i + 1 == tabpagenr() let s ..= '%#TabLineSel#' else let s ..= '%#TabLine#' endif " set the tab page number (for mouse clicks) let s ..= '%' .. (i + 1) .. 'T' " the label is made by MyTabLabel() let s ..= ' %{MyTabLabel(' .. (i + 1) .. ')} ' endfor " after the last tab page fill with TabLineFill and reset tab page nr let s ..= '%#TabLineFill#%T' " right-align the label to close the current tab page if tabpagenr('$') > 1 let s ..= '%=%#TabLine#%999Xclose' endif return sendfunctionNow the MyTabLabel() functionis called for eachtab page to get its label.function MyTabLabel(n) let buflist = tabpagebuflist(a:n) let winnr = tabpagewinnr(a:n) return bufname(buflist[winnr - 1])endfunctionThisis justa simplistic example that results inatab pages line thatresembles the default, but without addinga+ fora modified buffer ortruncating the names. You will want to reduce the width of labels inaclever way when thereis not enough room. Check the'columns' option for thespace available.==============================================================================5. Setting'tabpanel'tabpanelsetting-tabpanelThetabpanelisa vertical sidebar that displaystab page labels along theside of the window. It looks like this:+-----------+----------------------------------|(1) |text text text text text text text| ~/aaa.txt|text text text text text text text|(2) |text text text text text text text| ~/.vimrc |text text text text text text text|(3) |text text text text text text text| ~/bbb.js |text text text text text text text| ~/ccc.css|text text text text text text text| |text text text text text text text| |text text text text text text text| |text text text text text text textTo configure the tabpanel, use the following options:'tabpanel','showtabpanel' and'tabpanelopt'.The'tabpanel' optionfunctions similar to'statusline' or'tabline', and the'showtabpanel' optionfunctions similar to'laststatus' or'showtabline'.The "columns:" item of'tabpanelopt' optionspecifies the width of thetabpanel: +------ This width | <----+----->+-----------+----------------------------------|(1) |text text text text text text text| ~/aaa.txt|text text text text text text text|(2) |text text text text text text textThe "align:" item of the'tabpanelopt' option determines whether thetabpanelwill be displayed on the left or right side of the window:+----------------------------------+-----------|text text text text text text text|(1)|text text text text text text text| ~/aaa.txt|text text text text text text text|(2)The "vert" item of the'tabpanelopt' optionspecifies whethera verticalseparator should be displayed between thetabpanel and the display part of thewindow: +------ This is | v+-----------+----------------------------------|(1) |text text text text text text text| ~/aaa.txt|text text text text text text text|(2) |text text text text text text textThe vertical separator characteris taken from "tpl_vert" in'fillchars'.You can customize the appearance of thetab page labels using the highlightgroups:hl-TabPanelhl-TabPanelSelhl-TabPanelFill==============================================================================6. Setting'guitablabel'setting-guitablabelWhen theGUItab pages lineis displayed,'guitablabel' can be used tospecify the label to display for eachtab page. Unlike'tabline', whichspecifies the wholetab pages lineat once,'guitablabel'is used for eachlabel separately.'guitabtooltip'is very similar andis used for the tooltip of the same label.This only appears when the mouse pointer hovers over the label, thusitusuallyis longer. Only supported on some systems though.See the'statusline' option for the format of the value.The "%N" item can be used for the currenttab page number. Thev:lnumvariableis also set to this number when the optionis evaluated.The items that usea file name refer to the currentwindow of thetab page.Note thatsyntax highlightingis not used for the option. The %T and %Xitems are also ignored.A simple example that puts thetab page number and the buffer name in thelabel::set guitablabel=%N\ %fAn example that resembles the default'guitablabel': Show the number ofwindows in thetab page anda '+' if thereisa modified buffer:function GuiTabLabel() let label = '' let bufnrlist = tabpagebuflist(v:lnum) " Add '+' if one of the buffers in the tab page is modified for bufnr in bufnrlist if getbufvar(bufnr, "&modified") let label = '+' break endif endfor " Append the number of windows in the tab page if more than one let wincount = tabpagewinnr(v:lnum, '$') if wincount > 1 let label ..= wincount endif if label != '' let label ..= ' ' endif " Append the buffer name return label .. bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])endfunctionset guitablabel=%{GuiTabLabel()}Note that the functionmust be defined before setting the option, otherwiseyou get an error message for the function not being known.If you want to fall back to the default label, return an empty string.If you want to show something specific foratab page, you might want to useatab page local variable.t:var vim:tw=78:ts=8:noet:ft=help:norl: