Image Zoom

Let readers inspect meaningful standalone images with an optional native dialog.

Categories:

Components

Image Zoom progressively enhances eligible content images with one native dialog. It is useful for screenshots and architecture diagrams whose details may be hard to read at the document width. The original image remains complete when JavaScript or dialog support is unavailable.

When to use

Enable zoom when a reader benefits from seeing the source image at a larger size. Prefer a purpose-built crop or a clearer diagram when enlargement does not solve the readability problem. Decorative icons, logos embedded in prose, and linked thumbnails should retain their existing behavior.

Enable the feature

Image Zoom is disabled by default. Enable it for the whole site in Hugo configuration:

YAML

params:
  ui:
    image_zoom:
      enable: true

A page can override the site value in its front matter with the same structure. Use a real boolean:

YAML

params:
  ui:
    image_zoom:
      enable: false

Oink only includes the JavaScript runtime and dialog on an enabled page that has an eligible image. Enabling the switch alone adds no runtime to a text-only page.

Quick start

Source

Ordinary standalone Markdown images are eligible. The named imgproc form is useful when Oink should generate a smaller preview but open the original:

GO-HTML-TEMPLATE

{{< imgproc
  src="images/content-primitives/oink.webp"
  command="Fit"
  options="640x320"
  alt="OINK local-first documentation preview"
>}}
A processed preview with a **Markdown caption**.
{{< /imgproc >}}

Rendered result

Activate the image with a pointer, Enter, or Space. Close the dialog with Escape, the visible close button, or the backdrop.

OINK local-first documentation preview — The document displays a processed preview. Image Zoom opens the **original resource**, and closing the dialog restores focus to this trigger.

An image inside a link is deliberately skipped and remains a link:

Eligible images

Oink enhances a meaningful image when all of these conditions hold:

The image is standalone in a paragraph or figure, or Gallery marks it explicitly.
It has a nonempty alt value and usable source.
It is not inside a link, button, or element marked data-no-zoom.
It is not marked aria-hidden="true", role="presentation", or role="none".

Inline images among text and empty-alt decorative images are skipped. Authors can add data-no-zoom to an image or ancestor in trusted HTML when an otherwise eligible image should not open.

Named imgproc parameters

src , resource path , required: An exact page or global image resource.
command , enum , required: One of Fit, Resize, Fill, or Crop.
options , string , required: Nonempty Hugo image-processing options, such as 640x320.
alt , string: Meaningful alternative text. It is required for content images and omitted only with decorative=true.
decorative , boolean , default: false: When true, alt must be absent and Image Zoom is suppressed.

The optional shortcode body is a Markdown caption. The historical three-value positional imgproc form remains compatible, but new content should use the named form so alternative text is enforced at build time.

Interaction and fallback

Progressive enhancement wraps an eligible image in a real button with aria-haspopup="dialog". The native dialog moves focus to its close button, supports Escape, copies the image’s alternative text and direct caption, and restores focus after closing. Without JavaScript or HTMLDialogElement, the image and caption remain ordinary static content. Markdown, print, and RSS do not include dialog controls.

Deliberate limits

Version one does not implement dragging, panning, wheel zoom, editing, or previous and next image navigation. It also never downloads a remote image at build time. Use Gallery to group related images while reusing this same dialog.

JavaScript is required to load comments. View discussions on GitHub.