image.nvim

Depending on which ImageMagick processor you chose, use the corresponding configuration for Lazy.nvim.

Using magick_cli (Default)

Use this if you installed ImageMagick via your system package manager.

Using magick_rock (FFI)

Use this for better performance. Requires a LuaRocks setup.

For Lazy >= v11.*:

require("lazy").setup({
    rocks = {
        hererocks = true,  -- recommended if you do not have global installation of Lua 5.1.
    },
    spec = {
        {
            "3rd/image.nvim",
            opts = {}
        },
    },
})

For Lazy < v11.x (using luarocks.nvim):

{
    "vhyrro/luarocks.nvim",
    priority = 1001,
    opts = {
        rocks = { "magick" },
    },
},
{
    "3rd/image.nvim",
    dependencies = { "luarocks.nvim" },
    opts = {}
}

{
    "3rd/image.nvim",
    build = false,
    opts = {
        processor = "magick_cli",
    }
}

Use require("image").setup() to configure the plugin's behavior. Key configuration areas include:

• backend: The rendering engine. Options are "kitty" (recommended), "ueberzug", or "sixel".
• processor: The image processing engine. Options are "magick_cli" or "magick_rock".
• integrations: A table of per-filetype settings (e.g., markdown, asciidoc, neorg, rst, typst, html, css).
• hijack_file_patterns: A list of file extensions (e.g., "*.png", "*.jpg") that, when opened, will render the file as an image.
• max_height_window_percentage: Controls the maximum height of rendered images relative to the window.

require("image").setup({
  backend = "kitty", -- or "ueberzug" or "sixel"
  processor = "magick_cli", -- or "magick_rock"
  integrations = {
    markdown = {
      enabled = true,
      clear_in_insert_mode = false,
      download_remote_images = true,
      only_render_image_at_cursor = false,
      only_render_image_at_cursor_mode = "popup", -- or "inline"
      floating_windows = false,
      filetypes = { "markdown", "vimwiki" },
    },
    -- ... other integrations
  },
  max_height_window_percentage = 50,
  hijack_file_patterns = { "*.png", "*.jpg", "*.jpeg", "*.gif", "*.webp", "*.avif" },
})

The image module provides methods to load images from local files or URLs and manipulate their properties.

Loading Images

• api.from_file(path, options): Loads an image from an absolute path.
• api.from_url(url, options, callback): Loads an image from a URL. The callback receives the image object.

Image Options

• id: Optional string ID (defaults to random).
• window: Optional window ID to bind the image to.
• buffer: Optional buffer ID to bind the image to.
• with_virtual_padding: If true, pads vertically with extmarks.
• overlap: Optional positive integer for lines covered by the image.
• inline: If true, binds image to an extmark (required if with_virtual_padding is true).
• x, y, width, height: Geometry settings.

Image Methods

• image:render(): Renders the image.
• image:render(geometry): Updates geometry and renders.
• image:clear(): Clears the image.
• image:move(x, y): Moves the image.
• image:brightness(value): Changes brightness.
• image:saturation(value): Changes saturation.
• image:hue(value): Changes hue.

local api = require("image")

-- from a file
local image = api.from_file("/path/to/image.png", {
  id = "my_image_id",
  with_virtual_padding = true,
  inline = true,
  x = 1,
  y = 1,
  width = 10,
  height = 10
})

-- from a URL
api.from_url("https://gist.ro/s/remote.png", {
    -- options
}, function(img)
    -- callback
end)

image:render()
image:move(1, 1)
image:brightness(0.5)
image:clear()