Policies

Last updated: August 19th 2026
Super Images behaviour that applies across generation, cleanup, and Twig delivery is grouped under the policies key in config/super-images.php.
'policies' => [
    'encode' => [ /* … */ ],
    'geometry' => [ /* … */ ],
    'safety' => [ /* … */ ],
    'cleanup' => [ /* … */ ],
    'fallback' => [ /* … */ ],
],

Encode

Controls how encoded derivatives are written (metadata stripping, progressive JPEG, PNG compression level).
KeyDefaultEffect
stripMetadatatrueRemove EXIF/IPTC from output when the driver supports it
progressivefalseProgressive/interlaced output where supported
pngCompression6PNG compression level (0–9)

Geometry

KeyDefaultEffect
allowUpscalefalseWhen false, resize/fit operations will not enlarge beyond the source dimensions
sharpnesssharpDownscale sharpness preset or options (see below)

Sharpness

Controls Imagick Lanczos blur, post-downscale unsharp (Imagick/GD/libvips), and how crisp derivatives look versus softer defaults.
'policies' => [
    'geometry' => [
        'allowUpscale' => false,
        // Presets softest → sharpest:
        'sharpness' => 'sharp', // soft | normal | sharp | extra
    ],
],
Fine-tune without changing the preset name in the identity hash base:
'sharpness' => [
    'preset' => 'sharp',
    'blur' => 0.82, // Imagick resize blur (< 1 sharpens, > 1 softens)
    'unsharp' => [  // or false to disable
        'radius' => 0.0,
        'sigma' => 0.6,
        'amount' => 0.85,
        'threshold' => 0.02,
    ],
],

Changing sharpness regenerates derivatives (included in the generation identity). Prefer Imagick (or libvips) over GD for the sharpest downscales.

For WebP via cwebp, also see Encoders & optimizers (method, -sharp_yuv, custom arguments).

Safety

KeyDefaultEffect
maxSourcePixels40_000_000Reject sources whose width × height exceeds this limit after load

Cleanup

Automatic derivative removal tied to Craft asset lifecycle events. Uses a lightweight per-asset index stored under @storage/super-images/asset-index/{assetId}.json — not a database table and not a full storage scan.

KeyDefaultEffect
onAssetDeletetruePurge indexed derivatives before the Craft asset is deleted
onAssetReplacetruePurge indexed derivatives when an asset file is replaced, before new generation is enqueued

Each indexed entry records the derivative identity, storage path, and adapter handle. Purge deletes the storage object, removes the existence marker (for remote adapters), and clears the index file.

Preview artifacts under the preview/ namespace are handled separately — see CLI cleanup and cleanup.previewRetentionDays.

Bulk console cleanup (super-images/cleanup --orphaned / --all) is separately guarded by cleanup.generatedRetentionDays (default 365 days) so generated derivatives stay cached for at least a year by default, independent of the onAssetDelete/onAssetReplace hooks above — see CLI cleanup → Cache & retention.

Fallback

Optional Twig delivery fallback when planning fails (missing asset, invalid source, etc.). Applies to url(), img(), picture(), and srcset() — not to strict generate().

KeyDefaultEffect
enabledfalseWhen true, retry planning once with the fallback asset
assetIdnullCraft asset ID to use as fallback (must differ from the requested asset)
Example — show a placeholder image when a hero asset is missing:
'policies' => [
    'fallback' => [
        'enabled' => true,
        'assetId' => 42, // placeholder Asset in Craft
    ],
],
{{ craft.superImages.img(entry.heroImage.one(), { profile: 'responsive', variant: 'md' }) }}

If the hero asset cannot be resolved, Super Images plans delivery using asset 42 with the same profile/variant/format options. Fallback is attempted at most once per call.