Custom Previewers

Yazi's plugin system allows you to define custom previewer plugins that run arbitrary scripts to generate preview content. Previewers match on MIME type or URL pattern and can be prepended or appended to the built-in preview chain.

Plugin Structure

A previewer plugin is a directory with a main.lua entry point:

~/.config/yazi/plugins/<name>.yazi/
├── main.lua
├── README.md
└── LICENSE

HEIC Previewer Example

Apple's HEIC image format is not natively previewable. An HEIC previewer converts HEIC to JPEG for display:

-- ~/.config/yazi/plugins/heic-preview.yazi/main.lua
local heic_prev = require("heic-preview"):setup()

function heic_prev:peek(job)
	local url = tostring(job.file.url)
	local cache = ya.file_cache(job.file)

	if cache then
		-- Convert HEIC to JPEG via ImageMagick
		os.execute(string.format(
			'magick "%s"[0] -resize 800x600 "%s"', url, cache
		))
		ya.image_show(cache, job.area)
		return ya.hide()
	end
end

return heic_prev

Register it in yazi.toml:

[plugin]
prepend_previewers = [
  { mime = "image/heic", run = "heic-preview" },
  { mime = "image/heif", run = "heic-preview" },
]

RAF Previewer Example

Fujifilm RAF (Raw) files need conversion via dcraw or libraw:

-- ~/.config/yazi/plugins/raf-preview.yazi/main.lua
local raf_prev = require("raf-preview"):setup()

function raf_prev:peek(job)
	local cache = ya.file_cache(job.file)
	if cache then
		os.execute(string.format(
			'dcraw -c "%s" | magick - -resize 800x600 "%s"',
			tostring(job.file.url), cache
		))
		ya.image_show(cache, job.area)
		return ya.hide()
	end
end

return raf_prev

Registration:

[plugin]
prepend_previewers = [
  { mime = "image/x-fuji-raf", run = "raf-preview" },
]

Plugin Rules

Previewer entries in yazi.toml support two match fields:

Field	Matches	Example
mime	MIME type	"image/heic", "text/*", "*"
url	URL/glob pattern	"*.heic", "*.raf", "*.nkm"

Use mime when the system's file command provides reliable MIME detection. Use url as a fallback for obscure formats or when MIME detection is unavailable.

Prepending vs Appending

Mode	Behavior
prepend_previewers	Your plugin runs before built-in previewers — use for overriding or adding new formats
append_previewers	Your plugin runs after built-in previewers — use as a fallback

Ya Utility API for Previewers

Previewer plugins commonly use these ya.* functions:

Function	Purpose
ya.file_cache(file)	Get a cache file path for the given file
ya.image_show(path, area)	Display an image in the preview area
ya.image_precache(path)	Pre-cache an image in the background
ya.hide()	Hide the preview (after showing an image)
ya.sync(func)	Run code synchronously on the main thread

Previews with External Scripts

For complex previewers, delegate to an external shell script:

[plugin]
prepend_previewers = [
  { mime = "image/x-nikon-nef", run = """
    /path/to/nef-preview "$1" "$2" "$3"
  """ },
]

The script receives three arguments: $1 (file path), $2 (cache path), $3 (preview area). See the Plugin API Reference for details.