---
title: "Image zoom and lightbox features"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:image-zoom"
source: "Reference/ReStructuredText/Graphics/ImageZoom.rst"
rendered: "2026-09-24T12:09:25+00:00"
---

# Image zoom and lightbox features {#image-zoom}

<!-- TODO: no Markdown rendering for "versionadded" -->

The image zoom feature was introduced in render-guides version 0.36.0.

The TYPO3 documentation theme provides built-in image zoom and lightbox
features to enhance the viewing experience for images and figures. These
features allow readers to view images in greater detail without leaving
the documentation page.

## Available zoom modes {#image-zoom-modes}

The zoom functionality is controlled by the `:zoom:` option on figure
and image directives. The following zoom modes are available:

-   **`lightbox`**

    Click to open the image in a full-screen overlay dialog. The lightbox
    provides a dark backdrop and centers the image. Click outside the image
    or press Escape to close. A zoom indicator icon appears on the image.

    **Use case**: Screenshots, diagrams, and any image that benefits from
    full-screen viewing. This is the recommended mode for most images.

-   **`gallery`**

    Click to open the image in a gallery viewer with mouse wheel zoom
    and navigation between grouped images. Use the `:gallery:` option to
    group related images together.

    **Use case**: Series of screenshots, step-by-step tutorials, or image
    collections that should be navigable together.

-   **`inline`**

    Enables scroll wheel zoom directly on the image without opening an
    overlay. When zoomed, drag to pan. Double-click or press Escape to reset.

    **Use case**: Detailed diagrams or technical drawings that need frequent
    zoom inspection without leaving context.

-   **`lens`**

    A magnifier lens follows the cursor when hovering over the image,
    showing a zoomed view. A result panel appears beside the image with
    the magnified area.

    **Use case**: High-resolution images with fine details, such as UI
    mockups or detailed screenshots.

## Directive options {#image-zoom-options}

The following options are available for the figure and image directives:

-   **`:zoom:`**

    The zoom mode to use. One of: `lightbox`, `gallery`, `inline`, `lens`.

-   **`:gallery:`**

    Group name for gallery mode. Images with the same gallery name can be
    navigated together. Only used with `:zoom: gallery`.

-   **`:zoom-indicator:`**

    Whether to show the zoom indicator icon. Set to `false` to hide it.
    Default is `true` (shown).

-   **`:zoom-factor:`**

    Magnification factor for lens mode. Default is `2`. Higher values
    provide stronger magnification. Only used with `:zoom: lens`.

## Usage examples {#image-zoom-examples}

### Example 3: lightbox zoom {#image-zoom-example-3}

![Example screenshot](../../../_Images/a4.jpg)

```rst
..  figure:: /_Images/a4.jpg
    :alt: Example screenshot
    :zoom: lightbox
    :class: with-border with-shadow

    Click to open in lightbox.
```

### Example 4: gallery mode with grouped images {#image-zoom-example-4}

```rst
..  figure:: /_Images/step1.png
    :alt: Step 1
    :zoom: gallery
    :gallery: tutorial

    First step of the tutorial.

..  figure:: /_Images/step2.png
    :alt: Step 2
    :zoom: gallery
    :gallery: tutorial

    Second step - navigate with arrow keys.
```

### Example 5: inline scroll-wheel zoom {#image-zoom-example-5}

```rst
..  figure:: /_Images/diagram.png
    :alt: Architecture diagram
    :zoom: inline

    Use scroll wheel to zoom in/out directly on this image.
```

### Example 6: magnifier lens {#image-zoom-example-6}

```rst
..  figure:: /_Images/detailed-ui.png
    :alt: User interface mockup
    :zoom: lens

    Hover over the image to see a magnified view.
```

### Example 7: hidden zoom indicator {#image-zoom-example-7}

```rst
..  figure:: /_Images/screenshot.png
    :alt: Screenshot
    :zoom: lightbox
    :zoom-indicator: false

    Lightbox without visible indicator icon.
```

## Accessibility considerations {#image-zoom-accessibility}

All zoom modes are designed with accessibility in mind:

### Keyboard navigation {#image-zoom-keyboard}

-   **Lightbox and Gallery modes**: Full keyboard support

    -   `Tab` \- Navigate to image and controls
    -   `Enter` or `Space` \- Open lightbox/gallery
    -   `Escape` \- Close lightbox/gallery
    -   `Arrow Left` / `Arrow Right` \- Navigate between images (gallery)
    -   `+` / `-` \- Zoom in/out (gallery)
-   **Inline zoom mode**: Full keyboard support

    -   `Tab` \- Focus the image
    -   `+` / `-` \- Zoom in/out
    -   `Arrow keys` \- Pan when zoomed
    -   `Escape` or `0` \- Reset zoom
-   **Lens mode**: Keyboard activation supported

    -   `Tab` \- Focus the image
    -   `Enter` or `Space` \- Toggle lens on/off
    -   `Arrow keys` \- Move lens position
    -   `Escape` \- Deactivate lens

### Screen reader support {#image-zoom-screen-reader}

All zoom modes maintain proper ARIA attributes and provide descriptive
labels for assistive technologies. Always use the `:alt:` option to
provide descriptive alternative text for images.

### Reduced motion support {#image-zoom-reduced-motion}

The zoom functionality respects the `prefers-reduced-motion` media query.
When reduced motion is preferred, transitions and animations are disabled.

## Best practices {#image-zoom-best-practices}

-   Always include descriptive `:alt:` text for accessibility
-   Use `lightbox` as the default for most images
-   Use `:gallery:` to group related images for navigation
-   Use `inline` for technical diagrams that need frequent inspection
-   Combine with `:class: with-border with-shadow` for better visual presentation
-   Test zoom functionality with keyboard navigation