snacks.nvim/docs/image.md

🍿 image

Image viewer using the Kitty Graphics Protocol.

Supported terminals:

• kitty
• wezterm
• ghostty

In order to automatically display the image when openinng an image file, you need to enable the image plugin in your snacks config.

Supported image formats:

• PNG
• JPEG/JPG
• GIF
• BMP
• WEBP

ImageMagick is required to convert images to the supported formats (all except PNG).

📦 Setup

-- lazy.nvim
{
  "folke/snacks.nvim",
  ---@type snacks.Config
  opts = {
    image = {
      -- your image configuration comes here
      -- or leave it empty to use the default settings
      -- refer to the configuration section below
    }
  }
}

⚙️ Config

---@class snacks.image.Config
---@field file? string
---@field wo? vim.wo|{} options for windows showing the image
{
  force = false, -- try displaying the image, even if the terminal does not support it
  wo = {
    wrap = false,
    number = false,
    relativenumber = false,
    cursorcolumn = false,
    signcolumn = "no",
    foldcolumn = "0",
    list = false,
    spell = false,
    statuscolumn = "",
  },
}

📚 Types

---@class snacks.image.Env
---@field name string
---@field env table<string, string|true>
---@field supported? boolean default: false
---@field placeholders? boolean default: false
---@field setup? fun(): boolean?
---@field transform? fun(data: string): string
---@field detected? boolean

📦 Module

---@class snacks.image
---@field id number
---@field buf number
---@field opts snacks.image.Config
---@field file string
---@field augroup number
---@field _convert uv.uv_process_t?
Snacks.image = {}

Snacks.image.dim()

Get the dimensions of a PNG file

---@param file string
---@return number width, number height
Snacks.image.dim(file)

Snacks.image.env()

Snacks.image.env()

Snacks.image.new()

---@param buf number
---@param opts? snacks.image.Config
Snacks.image.new(buf, opts)

Snacks.image.supports()

Check if the file format is supported and the terminal supports the kitty graphics protocol

---@param file string
Snacks.image.supports(file)

Snacks.image.supports_file()

Check if the file format is supported

---@param file string
Snacks.image.supports_file(file)

Snacks.image.supports_terminal()

Check if the terminal supports the kitty graphics protocol

Snacks.image.supports_terminal()

image:close()

image:close()

image:convert()

---@param file string
image:convert(file)

image:create()

image:create()

image:grid_size()

image:grid_size()

image:hide()

image:hide()

image:ready()

image:ready()

image:render()

Renders the unicode placeholder grid in the buffer

---@param width number
---@param height number
image:render(width, height)

image:render_fallback()

image:render_fallback()

image:request()

---@param opts table<string, string|number>|{data?: string}
image:request(opts)

image:set_cursor()

---@param pos {[1]: number, [2]: number}
image:set_cursor(pos)

image:update()

image:update()

image:wins()

---@return number[]
image:wins()