Feature request

What are you trying to achieve?

With browser support for progressive/layered AVIF rendering actively advancing (notably tracked under Interop Issue #1459), web developers will need to generate single-file progressive AVIF assets directly via sharp.

Upstream libavif supports encoding layered and progressive AVIF files (via flags like --progressive and --layered, along with per-layer quality/scaling settings in avifenc). Currently, sharp does not expose these underlying libvips / libavif options in .avif().

Exposing this capability will allow Node.js build pipelines and meta-frameworks (e.g., Astro, Next.js, Nuxt) to output progressive AVIF images natively without relying on multi-request blur/placeholder client-side workarounds.

When you searched for similar feature requests, what did you find that might be related?

/

What would you expect the API to look like?

Because layered AVIF encoding in libavif supports multi-pass options (defining up to 4 layers with distinct spatial scaling and quality parameters), the API should ideally support both a convenient boolean shortcut and a granular configuration object.

// 1. Simple convenience shortcut (uses default progressive layer heuristics)
await sharp(input)
  .avif({
    progressive: true
  })
  .toFile('output.avif');

// 2. Granular layered control
await sharp(input)
  .avif({
    progressive: {
      layers: 2,                   // Number of progressive passes (1–4)
      quality: [20, 80],           // Base preview -> Mid -> Full quality per layer
      scalingMode: ['1/4', '1/1']  // Spatial resolution scaling per layer
    }
  })
  .toFile('output.avif');

Exposing an object structure ensures developers can optimize the base layer size (e.g., tiny low-quality pass) while retaining full visual quality in the final layer.

What alternatives have you considered?

/

Please provide sample image(s) that help explain this feature

• Interop Issue & Technical Context: Progressive image rendering for JPEG XL and AVIF web-platform-tests/interop#1459
• libavif encoder reference implementation for progressive/layered parameters: https://github.com/AOMediaCodec/libavif/blob/main/apps/avifenc.c