textprop.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarDisplaying text with properties attached.textproptext-properties1. Introductiontext-prop-intro2. Functionstext-prop-functions3. When text changestext-prop-changes{not able to use text properties when the+textprop feature wasdisabledat compile time}==============================================================================1. Introductiontext-prop-introText properties can be attached to text ina buffer. They will move with thetext: If lines are deleted or inserted the properties move with the text theyare attached to. Also when inserting/deleting text in the line before thetext property. And when inserting/deleting text inside the text property,itwill increase/decrease in size.The main use for text propertiesis to highlight text. This can be seenasareplacement forsyntax highlighting. Instead of defining patterns to matchthe text, the highlightingis set bya script, possibly using the output of anexternal parser. This only needs to be done once, not every time whenredrawing the screen, thus can be much faster, after the initial cost ofattaching the text properties.Text properties can also be used for other purposes to identify text. Forexample, adda text property ona function name, so thata search can bedefined to jump to the next/previous function.A text propertyis attachedata specific line and column, and hasa specifiedlength. The property can span multiple lines.A text property has these fields:"id"a number to be usedas desired"type"the name ofa property typeProperty TypesE971A text property normally has the name ofa property type, which defineshow to highlight the text. The property type can have these entries:"highlight"name of the highlight group to use"combine"when omitted orTRUE the text property highlightingiscombined with anysyntax highlighting; whenFALSE thetext property highlighting replaces thesyntaxhighlighting"priority"when properties overlap, the one with the highestpriority will be used."start_incl"whenTRUE insertsat the start position will beincluded in the text property"end_incl"whenTRUE insertsat theend position will beincluded in the text propertyExampleSuppose line 11 ina buffer has this text (excluding the indent):The number 123is smaller than 4567.To highlight the numbers in this text:call prop_type_add('number', {'highlight': 'Constant'})call prop_add(11, 12, {'length': 3, 'type': 'number'})call prop_add(11, 32, {'length': 4, 'type': 'number'})Tryinserting ordeleting lines above the text, you will see that the textproperties stick to the text, thus the line numberis adjustedas needed.Setting "start_incl" and "end_incl"is useful when whitespace surrounds thetext, e.g. fora function name. Usingfalseis useful when the text startsand/or ends witha specific character, suchas thequote surroundinga string.func FuncName(arg) ^^^^^^^^ property with start_incl and end_incl setvar = "text"; ^^^^^^ property with start_incl and end_incl not setNevertheless, when textis inserted or deleted the text may need to be parsedand the text properties updated. But this can be done asynchronously.Internal errorE967If you see E967, please report the bug. You cando thisat Github:https://github.com/vim/vim/issues/new==============================================================================2. Functionstext-prop-functionsManipulating text property types:prop_type_add({name},{props})definea new property typeprop_type_change({name},{props})change an existing property typeprop_type_delete({name} [,{props}])deletea property typeprop_type_get({name} [,{props}])get property type valuesprop_type_list([{props}])getlist of property typesManipulating text properties:prop_add({lnum},{col},{props})adda text propertyprop_add_list({props}, [{item}, ...])adda text propertyat multiplepositions.prop_clear({lnum} [,{lnum-end} [,{bufnr}]])remove all text propertiesprop_find({props} [,{direction}])search fora text propertyprop_list({lnum} [,{props}])text properties in{lnum}prop_remove({props} [,{lnum} [,{lnum-end}]])removea text propertytext-prop-functions-detailsprop_add()E965prop_add({lnum},{col},{props})Attacha text propertyat position{lnum},{col}.{col}iscounted in bytes, use one for the first column.If{lnum}is invalid an erroris given.E966If{col}is invalid an erroris given.E964{props}isa dictionary with these fields: typename of the text property type lengthlength of text in bytes, can only be usedfora property that does not continue inanother line; can be zero end_lnumline number for theend of text (inclusive) end_colcolumn just after the text; not used when"length"is present; when{col} and "end_col"are equal, and "end_lnum"is omitted or equalto{lnum}, thisisa zero-width text property bufnrbuffer to add the property to; when omittedthe current bufferis used iduser defined ID for the property;must beanumber, should be positiveE1510;when using "text" then "id"must not bepresent and will be set automatically toanegative number; otherwise zerois usedE1305 texttext to be displayed before{col}, orabove/below the line if{col}is zero; prependand/or append spaces for padding withhighlighting; cannot be used with "length","end_lnum" and "end_col"Seevirtual-text for more information.E1294 text_alignwhen "text"is present and{col}is zero;specifies where to display the text: after after theend of the line right right aligned in thewindow (unless the text wraps to the next screen line) below in the next screen line above just above the lineWhen omitted "after"is used. Only one"right" property can fit in each line, ifthere are two or more these willgo inaseparate line (still right aligned). text_padding_leftE1296used when "text"is present and{col}is zero;padding between theend of the text line(leftmost column for "above" and "below") andthe virtual text, not highlighted text_wrapwhen "text"is present and{col}is zero,specifies what happens if the text doesn'tfit: wrap wrap the text to the next line truncate truncate the text to makeit fitWhen omitted "truncate"is used.Note that this applies to the individual textproperty, the'wrap' option sets the overallbehaviorAll fields except "type" are optional.Itis an error when both "length" and "end_lnum" or "end_col"are given. Either use "length" or "end_col" fora propertywithin one line, or use "end_lnum" and "end_col" foraproperty that spans more than one line.When neither "length" nor "end_col" are given the propertywill be zero-width. That meansit will move with the text,asa kind of mark. One character will be highlighted, if thetypespecifies highlighting.The property canend exactlyat the last character of thetext, or just after it. In the last case, if textis appendedto the line, the text property size will increase, also whenthe property type does not have "end_incl" set."type" will first be looked up in the buffer the propertyisadded to. When not found, the global property types are used.If not found an erroris given.virtual-textWhen "text"is used and the columnis non-zero then this textwill be displayedat the specified start location of the textproperty. The text of the buffer line will be shifted to makeroom. Thisis called "virtual text".When the columnis zero the virtual text will appear above,after or below the buffer text. The "text_align" and"text_wrap" arguments determine howitis displayed.To separate the virtual text from the buffer text prependand/or append spaces to the "text" field or use the"text_padding_left" value.Make sure to usea highlight that makes clear to the user thatthisis virtual text, otherwiseit will be very confusing thatthe text cannot be edited. When using "above" you need tomake clear this text belongs to the text line below it, whenusing "below" you need to make sureit belongs to the textline above it.The text will be displayed butitis not part of the actualbuffer line, the cursor cannot be placed on it.A mouse clickin the text will move the cursor to the first character afterthe text, or the last character of the line.AnyTab and othercontrol character in the text will bechanged toaspace (Rationale: otherwise the size of the textis difficult to compute).A negative "id" will be chosen andis returned.Before text properties with text were supportedit waspossible to usea negative "id", even though this was veryrare. Now that negative "id"s are reserved for textproperties with text an erroris given when usinga negative"id". Whena text property with text already exists usinganegative "id" results inE1293. Ifa negative "id" wasused and latera text property with textis added results inE1339.Can also be usedasamethod:GetLnum()->prop_add(col, props)Return type:Numberprop_add_list({props}, [{item}, ...])prop_add_list()Similar to prop_add(), but attachesa text propertyatmultiple positions ina buffer.{props}isa dictionary with these fields: bufnrbuffer to add the property to; when omittedthe current bufferis used iduser defined ID for the property;must beanumber; when omitted zerois used typename of the text property typeAll fields except "type" are optional.The second argumentisaList of items, where each{item}isalist thatspecifies thestarting and ending position of thetext: [{lnum},{col},{end-lnum},{end-col}]or: [{lnum},{col},{end-lnum},{end-col},{id}]The first two items{lnum} and{col} specify thestartingposition of the text where the property will be attached.The next two items{end-lnum} and{end-col} specify theposition just after the text.An optional fifth item{id} can be used to givea different IDtoa property. When omitted the ID from{props}is used,falling back to zero if none are present.Itis not possible to adda text property witha "text" fieldhere.Example:call prop_add_list(#{type: 'MyProp', id: 2},\ [[1, 4, 1, 7],\ [1, 15, 1, 20],\ [2, 30, 3, 30]])Can also be usedasamethod:GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]])prop_clear({lnum} [,{lnum-end} [,{props}]])prop_clear()Remove all text properties from line{lnum}.When{lnum-end}is given, remove all text properties from line{lnum} to{lnum-end} (inclusive).When{props} containsa "bufnr" item use this buffer,otherwise use the current buffer.Can also be usedasamethod:GetLnum()->prop_clear()Return type:Numberprop_find({props} [,{direction}])prop_find()Search fora text propertyas specified with{props}: idproperty with this ID typeproperty with this type name both"id" and "type"must both match bufnrbuffer to search in; when presentastart position with "lnum" and "col"must be given; when omitted thecurrent bufferis used lnumstart in this line (when omitted startat the cursor) colstartat this column (when omittedand "lnum"is given: use column 1,otherwise startat the cursor) skipstartdo not look fora matchat the startpositionA property matches when either "id" or "type" matches.{direction} can be "f" for forward and "b" for backward. Whenomitted forward searchis performed.Ifa matchis found thenaDictis returned with the entriesas with prop_list(), and additionally an "lnum" entry.If no matchis found then an emptyDictis returned.Return type: dict<any>prop_list({lnum} [,{props}])prop_list()ReturnsaList with all the text properties in line{lnum}.The following optional items are supported in{props}: bufnruse this buffer instead of the current buffer end_lnumreturn text properties in all the linesbetween{lnum} and{end_lnum} (inclusive).A negative valueis usedas an offset from thelast buffer line; -1 refers to the last bufferline. typesList of property type names. Return only textproperties that match one of the type names. idsList of property identifiers. Return onlytext properties with one of these identifiers.The properties are ordered bystarting column and priority.Each propertyisaDict with these entries: lnumstarting line number. Present only whenreturning text properties between{lnum} and{end_lnum}. colstarting column lengthlength in bytes, one more if line breakisincluded idproperty ID texttext to be displayed before{col}. Onlypresent forvirtual-text properties. text_alignalignment property ofvirtual-text. text_padding_leftleft padding used for virtual text. text_wrapspecifies whethervirtual-textis wrapped. typename of the property type, omitted ifthe type was deleted type_bufnrbuffer number for which this type was defined;0 if the typeis global startwhenTRUE property starts in this lineendwhenTRUE property ends in this lineWhen "start"is zero the property started ina previous line,the current oneisa continuation.When "end"is zero the property continues in the next line.The line break after this lineis included.Returns an emptylist on error.Examples: " get text properties placed in line 5 echo prop_list(5) " get text properties placed in line 20 in buffer 4 echo prop_list(20, {'bufnr': 4}) " get all the text properties between line 1 and 20 echo prop_list(1, {'end_lnum': 20}) " get all the text properties of type 'myprop' echo prop_list(1, {'types': ['myprop'],\ 'end_lnum': -1}) " get all the text properties of type 'prop1' or 'prop2' echo prop_list(1, {'types': ['prop1', 'prop2'],\ 'end_lnum': -1}) " get all the text properties with ID 8 echo prop_list(1, {'ids': [8], 'end_lnum': line('$')}) " get all the text properties with ID 10 and 20 echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1}) " get text properties with type 'myprop' and ID 100 " in buffer 4. echo prop_list(1, {'bufnr': 4, 'types': ['myprop'],\ 'ids': [100], 'end_lnum': -1})Can also be usedasamethod:GetLnum()->prop_list()Return type: list<dict<any>> or list<any>prop_remove()E968E860prop_remove({props} [,{lnum} [,{lnum-end}]])Removea matching text property from line{lnum}. When{lnum-end}is given, remove matching text properties from line{lnum} to{lnum-end} (inclusive).When{lnum}is omitted remove matching text properties fromall lines (this requires going over all lines, thus will beabit slow fora buffer with many lines).{props}isa dictionary with these fields: idremove text properties with this ID typeremove text properties with this type name typesremove text properties with type names in thisList both"id" and "type"/"types"must both match bufnruse this buffer instead of the current one allwhenTRUE remove all matching text properties,not just the first oneOnly one of "type" and "types" may be supplied.E1295A property matches when either "id" or one of the suppliedtypes matches.If buffer "bufnr" does not exist you get an error message.If buffer "bufnr"is not loaded then nothing happens.Returns the number of properties that were removed.Can also be usedasamethod:GetProps()->prop_remove()Return type:Numberprop_type_add({name},{props})prop_type_add()E969E970Adda text property type{name}. Ifa property type with thisname already exists an erroris given. Nothingis returned.{props}isa dictionary with these optional fields: bufnrdefine the property only for this buffer; thisavoids name collisions and automaticallyclears the property types when the bufferisdeleted. highlightname of highlight group to use prioritywhena character has multiple textproperties the one with the highest prioritywill be used; negative values can be used, thedefault priorityis zero combinewhen omitted orTRUE combine the highlightwith anysyntax highlight; whenFALSEsyntaxhighlight will not be used overridewhenTRUE the highlight overrides any other,including'cursorline' andVisual start_inclwhenTRUE insertsat the start position willbe included in the text property end_inclwhenTRUE insertsat theend position will beincluded in the text propertyCan also be usedasamethod:GetPropName()->prop_type_add(props)Return type:Numberprop_type_change({name},{props})prop_type_change()Change properties of an existing text property type. Ifaproperty with this name does not exist an erroris given.The{props} argumentis just likeprop_type_add().Can also be usedasamethod:GetPropName()->prop_type_change(props)Return type:Numberprop_type_delete({name} [,{props}])prop_type_delete()Remove the text property type{name}. When text propertiesusing the type{name} are still in place, they will not havean effect and can no longer be removed by name.{props} can containa "bufnr" item. Whenitis given, deletea property type from this buffer instead of from the globalproperty types.When text property type{name}is not found thereis no error.Can also be usedasamethod:GetPropName()->prop_type_delete()Return type:Numberprop_type_get({name} [,{props}])prop_type_get()Returns the properties of property type{name}. Thisisadictionary with the same fieldsas was given toprop_type_add().When the property type{name} does not exist, an emptydictionaryis returned.{props} can containa "bufnr" item. Whenitis given, usethis buffer instead of the global property types.Can also be usedasamethod:GetPropName()->prop_type_get()Return type: dict<any>prop_type_list([{props}])prop_type_list()Returnsalist with all property type names.{props} can containa "bufnr" item. Whenitis given, usethis buffer instead of the global property types.Return type: list<string> or list<any>==============================================================================3. When text changestext-prop-changesVim willdo its best to keep the text properties on the text whereit wasattached. Wheninserting ordeleting text the properties after the changewill move accordingly.When textis deleted anda text property no longer includes any text,itisdeleted. However,a text property that was definedas zero-width will remain,unless the whole lineis deleted.E275Whena bufferis unloaded, all the text properties are gone. Thereis no wayto store the properties ina file. You can only re-create them. Whenabufferis hidden the textis preserved and so are the text properties. Itisnot possible to add text properties to an unloaded buffer.When using replace mode, the text properties stay on the same characterpositions, even though the characters themselves change.To update text properties after the text was changed,installa callback withlistener_add(). E.g, if yourplugin doesspell checking, you can have thecallback update spelling mistakes in the changed text. Vim will move theproperties below the changed text, so that they still highlight the same text,thus you don't need to update these.text-prop-clearedText property columns are not updated or copied:- When setting the line withsetline() or through an interface, suchas Lua,Tcl or Python. Vim does not know what text got inserted or deleted.- Witha command like:move, which takesa line of text out of context. vim:tw=78:ts=8:noet:ft=help:norl: