1- *popup.txt* For Vim version 9.2. Last change: 2026 Jul 29
1+ *popup.txt* For Vim version 9.2. Last change: 2026 Sep 30
22
33
44 VIM REFERENCE MANUAL by Bram Moolenaar
@@ -427,6 +427,11 @@ popup_getoptions({id}) *popup_getoptions()*
427427 "textprop", "textpropid" and "textpropwin" are only present
428428 when "textprop" was set.
429429
430+ The "image" entry is a dictionary with the same fields as
431+ returned by | image_info() | . Note that if the image is created
432+ directly by the popup, the "id" field will not be present, see
433+ | popup-image | .
434+
430435 If popup window {id} is not found an empty Dict is returned.
431436
432437 Can also be used as a | method | : >
@@ -609,6 +614,7 @@ popup_setoptions({id}, {options}) *popup_setoptions()*
609614 firstline
610615 flip
611616 highlight
617+ image
612618 mapping
613619 mask
614620 moved
@@ -801,18 +807,9 @@ The second argument of |popup_create()| is a dictionary with options:
801807 underlying text, making it partially transparent.
802808 Requires 'termguicolors' to be set.
803809 Also see | popup-opacity | .
804- image Dictionary describing a raw RGB or RGBA pixel buffer
805- to render inside the popup. When set the popup
806- auto-sizes its cell box from the image's pixel
807- dimensions, so "minwidth" / "minheight" / "maxwidth" /
808- "maxheight" do not need to be set by hand. Keys:
809- data | Blob | of bytes; length must equal
810- width*height*3 (RGB) or width*height*4
811- (RGBA).
812- width image width in pixels.
813- height image height in pixels.
814- Use an empty dictionary to remove a previously set
815- image. See | popup-image | .
810+ image Dictionary for displaying an image. See | image_add() |
811+ for required fields, or you can provide the "id" field
812+ only, see | popup-image | .
816813 padding List with numbers, defining the padding
817814 above/right/below/left of the popup (similar to CSS).
818815 An empty list uses a padding of 1 all around. The
@@ -1170,44 +1167,60 @@ For example, to make the last 10 columns of the last line transparent:
11701167To make the four corners transparent:
11711168 [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
11721169
1173- POPUP IMAGE *popup-image*
1174-
1175- A popup window can render an image instead of (or on top of) text by passing
1176- an "image" dictionary to | popup_create() | or | popup_setoptions() | . The caller
1177- supplies an already-decoded raw pixel buffer and Vim emits it through
1178- whichever backend is available at runtime:
1179-
1180- sixel DEC sixel DCS sequence on a sixel-capable terminal.
1181- | +image_sixel | . Detected automatically; the buffer is also
1182- cropped one cell above the screen edge to avoid sixel-induced
1183- terminal scrolling.
1184- kitty kitty graphics protocol APC sequence on terminals that support it
1185- (kitty, ghostty, WezTerm, Konsole, ...). | +image_kitty | .
1186- Detected by actively querying the terminal.
1187- GDI StretchDIBits onto the GUI canvas on the MS-Windows GUI.
1188- | +image_gdi | .
1189- Cairo composite onto a cairo_image_surface_t on the GTK GUI
1190- (covers GTK 2 and GTK 3). | +image_cairo | .
1191- GDK Use GdkTexture, which uploads the image onto the GPU for faster
1192- rendering (only for GTK 4). | +image_gdk |
1193-
1194- Vim itself does NOT link against libpng, libjpeg, libwebp or any image
1195- decoder. Format decoding is left to the caller, who can pipe the file through
1196- any external tool (GraphicsMagick, ImageMagick, ffmpeg, a custom converter,
1197- ...) and pass the resulting bytes via a | Blob | .
1198-
1199- The "image" dictionary accepts:
1200- data | Blob | of bytes. Length must equal width*height*3 for RGB,
1201- or width*height*4 for RGBA. RGBA buffers are alpha-composited
1202- over the popup's background.
1203- width image width in pixels.
1204- height image height in pixels.
1205-
1206- The popup's cell box is derived from the pixel dimensions and the terminal /
1207- GUI cell metrics, so the caller does not normally have to set "minwidth" /
1208- "minheight" / "maxwidth" / "maxheight".
1209-
1210- For RGBA buffers that need to blend cleanly into the editor's actual backdrop
1170+ POPUP IMAGE *image* *popup-image*
1171+
1172+ Vim is capable of displaying graphical images, in both the terminal and GUI.
1173+ To do this, it must link with the pixman library, which you may install via
1174+ your package manager on Unix, or via vcpkg on MS-Windows. You may see if
1175+ images are supported by checking | +image | and | +image_popup | .
1176+
1177+ A popup window may additionally render an image. To do this, pass a field
1178+ named "image" containing a dictionary to | popup_create() | or
1179+ | popup_setoptions() | . The dictionary may either have the same fields as in
1180+ | image_add() | , or it may reference an image via its ID using the "id" field.
1181+ The "id" field is prioritized first, see | image_add() | , | image_discard() | , and
1182+ | image_info() | .
1183+
1184+ When an image is directly created by a popup window (e.g. "id" is not used),
1185+ then it is considered internal and can not be referenced anywhere else.
1186+
1187+ To unset a previously set image from a popup window pass an empty dictionary: >
1188+ call popup_setoptions(winid, #{image: {}})
1189+ <
1190+ *image-backends*
1191+ There are two terminal image protocols supported on all platforms. The
1192+ protocol to use is chosen using the 'imageprotocol' option:
1193+
1194+ sixel Uses the sixel protocol to display images.
1195+ kitty Uses the kitty graphics protocol. This is the recommended
1196+ protocol to use in the terminal if it is available, as it is much
1197+ more performant than sixel.
1198+
1199+ When using the GUI, the GTK4, GTK3, and Win32 versions of Vim are supported.
1200+
1201+ To see what image backend is currently being used, use the | v:imagebackend |
1202+ variable.
1203+
1204+ *image-options*
1205+ When passing an RGBA buffer, Vim expects it to be endian independent and non
1206+ alpha pre-multiplied. For RGB images, each pixel should be exactly 3 bytes,
1207+ a padding byte is not supported by Vim.
1208+
1209+ The dimensions of a popup containing an image are automatically calculated
1210+ based on the image dimensions and terminal/GUI cell size. However, you may
1211+ override it using the "minwidth", "minheight", "maxwidth", and "maxheight"
1212+ fields.
1213+
1214+ Images are not scaled, if a popup window is smaller than the image it
1215+ contains, then the image will be cropped instead.
1216+
1217+ *image-animation*
1218+ The image of a popup window can be changed at runtime using
1219+ | popup_setoptions() | . When the new image has the same format, width, and
1220+ height as the existing image, the existing image will be modified in place.
1221+ This is performant enough for frame-by-frame animation, using a | timer | .
1222+
1223+ For RGBA buffers that need to blend cleanly into the editor's actual backdrop,
12111224the script can call | getbgcolor() | to obtain the current background colour as
12121225[r, g, b] and pre-composite anti-aliased edges against it.
12131226
@@ -1232,15 +1245,6 @@ raw RGB bytes: >
12321245 \ line: 1, col: 1, border: [], padding: [0, 0, 0, 0],
12331246 \ })
12341247
1235- | popup_setoptions() | . When the new
1236- buffer has the same width and height as the current one the pixels are swapped
1237- in place, which is fast enough to drive frame-by-frame animation from a
1238- | timer | . | popup_getoptions() | returns the same dictionary back; the "data"
1239- entry is a fresh blob copy independent of the popup's internal buffer.
1240-
1241- To remove a previously set image pass an empty dictionary: >
1242- call popup_setoptions(winid, #{image: {}})
1243-
12441248==============================================================================
124512494. Examples *popup-examples*
12461250
0 commit comments