---
title: "Usage"
manual: "Image Optimization for TYPO3"
version: "2.6"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-image-optimize:usage@2.6"
source: "Usage/Index.rst"
rendered: "2026-09-25T11:13:49+00:00"
---

# Usage {#usage}

This chapter shows practical examples for integrating
responsive images into your Fluid templates and for operating
the command-line tools that ship with the extension.

## Register the namespace {#usage-namespace}

Add the ViewHelper namespace at the top of your Fluid
template or register it globally:

**Inline namespace declaration**

```html
{namespace nr=Netresearch\NrImageOptimize\ViewHelpers}
```

## Basic responsive image {#usage-basic-example}

**Simple responsive image**

```html
<nr:sourceSet file="{image}"
              width="1200"
              height="800"
              sizes="(max-width: 768px) 100vw, 50vw"
/>
```

Quality is not configurable per call: the ViewHelper always
emits its default quality of 75 into the generated
`/processed/...q<n>...` URL.

## Responsive width-based srcset {#usage-responsive-srcset}

Enable width-based `srcset` generation with a `sizes`
attribute for improved responsive image handling. This is
opt-in per usage.

**Enable responsive srcset with default variants**

```html
<nr:sourceSet
    path="{f:uri.image(
        image: image,
        maxWidth: size,
        cropVariant: 'default'
    )}"
    width="{size}"
    height="{size * ratio}"
    alt="{image.properties.alternative}"
    lazyload="1"
    mode="fit"
    responsiveSrcset="1"
/>
```

### Custom width variants {#usage-custom-variants}

**Specify custom breakpoints for srcset**

```html
<nr:sourceSet
    path="{f:uri.image(
        image: image,
        maxWidth: size,
        cropVariant: 'default'
    )}"
    width="{size}"
    height="{size * ratio}"
    responsiveSrcset="1"
    widthVariants="320,640,1024,1920,2560"
    sizes="(max-width: 640px) 100vw,
           (max-width: 1024px) 75vw, 50vw"
/>
```

## Output comparison {#usage-output-comparison}

**Legacy mode** (`responsiveSrcset=false` or not set):

**Density-based 2x srcset output**

```html
<img src="/processed/fileadmin/image.w625h250m1q75.jpg"
     srcset="/processed/fileadmin/image.w1250h500m1q75.jpg x2"
     width="625"
     height="250"
     loading="lazy">
```

**Responsive mode** (`responsiveSrcset=true`):

**Width-based srcset output**

```html
<img src="/processed/fileadmin/image.w1250h1250m1q75.png"
     srcset="/processed/fileadmin/image.w480h480m1q75.png 480w,
             /processed/fileadmin/image.w576h576m1q75.png 576w,
             /processed/fileadmin/image.w640h640m1q75.png 640w,
             /processed/fileadmin/image.w768h768m1q75.png 768w,
             /processed/fileadmin/image.w992h992m1q75.png 992w,
             /processed/fileadmin/image.w1200h1200m1q75.png 1200w,
             /processed/fileadmin/image.w1800h1800m1q75.png 1800w"
     sizes="auto, (min-width: 992px) 991px, 100vw"
     width="991"
     loading="lazy"
     alt="Image">
```

## Public images only: absolute URLs are passed through {#usage-protected-files}

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

Absolute URLs, data: URIs, and URLs with a query string are
passed through unchanged and rendered as a plain <img> tag.

The `/processed/` endpoint is designed for **public files** only.
It resolves the given path below the public web root and writes the
generated variants as static files into `public/processed/`,
where the web server delivers them directly — without any access
check.

Files in non-public FAL storages (`is_public = 0`) can therefore
not be processed. Extensions such as
[fal_securedownload](https://extensions.typo3.org/extension/fal_securedownload)
resolve such files to tokenized eID URLs
(`/index.php?eID=dumpFile&...`) whose delivery runs through TYPO3
and performs a permission check on every request.

The ViewHelper detects absolute URLs (`http://`, `https://`,
`//`), `data:` URIs, and URLs containing a query string and
passes them through unchanged, rendering a plain `<img>` tag with
the URL as `src`:

**Output for a file from a protected storage**

```html
<picture>
<img src="https://example.org/index.php?eID=dumpFile&amp;t=f&amp;f=42&amp;fal_token=..."
     width="400"
     height="300"
     alt="Protected image" />
</picture>
```

> [!IMPORTANT]
> **Trade-off for passed-through URLs**
>
> -   No `srcset`/`sizes` attributes and no per-breakpoint
>     `<source>` elements are generated — the browser always
>     loads the image in its original dimensions.
> -   No WebP/AVIF variants and no quality optimization are
>     applied.
> -   In return, the access control of the generating extension
>     (e.g. fal_securedownload) stays fully intact, because the
>     URL — including its access token — is emitted unchanged.

If you need optimized variants of images in protected storages,
generate them with TYPO3's own image processing (for example
`f:image` or the `ImageService`). Processed files are then
created inside the protected storage's processing folder and are
delivered through the same secure-download mechanism, keeping the
permission check intact.

## Fetch priority for Core Web Vitals {#usage-fetchpriority}

Use the `fetchpriority` attribute to hint the browser
about resource prioritization, improving Largest Contentful
Paint (LCP) scores:

**High priority for above-the-fold hero image**

```html
<nr:sourceSet file="{heroImage}"
              width="1920"
              height="1080"
              fetchpriority="high"
/>
```

## Command-line tools {#usage-cli}

Both commands read the FAL index directly and process eligible
image files (`image/jpeg`, `image/gif`, `image/png`) on
online storages. Per-file storage permission evaluation is
temporarily disabled and restored in a `finally` block so
long-running CLI runs don't leak state across iterations or
require a BE user context.

### Bulk optimize images {#usage-cli-optimize}

The `nr:image:optimize` command compresses every eligible
PNG, GIF, and JPEG file across all storages (or a restricted
subset) using the installed optimizer binaries. The original
file is replaced in place only when the tool produces a
smaller result.

**Preview what would be processed**

```bash
vendor/bin/typo3 nr:image:optimize --dry-run
```

**Compress storage 1 with lossy JPEG quality 85**

```bash
vendor/bin/typo3 nr:image:optimize \
    --storages=1 \
    --jpeg-quality=85 \
    --strip-metadata
```

Options:

-   **`--dry-run`**

    Only analyze; do not modify files.

-   **`--storages`**

    Restrict to specific storage UIDs. Accepts repeated
    occurrences or a comma-separated list.

-   **`--jpeg-quality`**

    Lossy JPEG quality 0--100. Omit for lossless JPEG
    optimization.

-   **`--strip-metadata`**

    Remove EXIF and comments when the tool supports it.

### Analyze optimization potential {#usage-cli-analyze}

The `nr:image:analyze` command estimates how much disk
space could be saved by running `nr:image:optimize` or by
downscaling oversized originals. It is purely heuristic --
no external binaries are invoked, so it runs quickly even on
large installations.

**Report potential for storage 1**

```bash
vendor/bin/typo3 nr:image:analyze --storages=1
```

Options:

-   **`--storages`**

    Restrict to specific storage UIDs.

-   **`--max-width` / `--max-height`**

    Target display box (default 2560 x 1440). Images larger
    than this box are assumed to be downscaled and the
    estimate factors in the area reduction.

-   **`--min-size`**

    Skip files smaller than this many bytes (default
    512000). Prevents noise from already-tiny images.