Image Transforms

Localess asset URLs support on-demand image transformation via query parameters. Append a parameter to any asset CDN URL to get back a resized, reformatted, or quality-adjusted image — without uploading multiple size variants and without a third-party image CDN.

This is useful for responsive images, thumbnails, and format optimization. The transformation happens server-side and the result is cached at the CDN edge.

URL Parameter Reference

Append parameters to any asset URL returned by client.assetLink() or resolveAsset().

Resize Behaviour (w / h)

Special Cases

• SVG — always passed through; w, h, and f are ignored.
• Animated WebP or GIF without thumbnail — passed through unchanged (cannot resize animated files).
• Animated WebP or GIF with thumbnail — first frame extracted, then w/h/f apply normally.
• Video with w + thumbnail — frame extracted via FFmpeg, then resized with Sharp; output defaults to image/webp.

Combine parameters with &:

https://my-space.web.app/api/v1/spaces/abc123/assets/hero.jpg?w=1200&q=80&f=webp

Examples

Resize to a fixed width

/api/v1/spaces/abc123/assets/hero.jpg?w=800

Returns the image at 800 px wide. Height scales proportionally to preserve the aspect ratio.

Resize to a fixed height

/api/v1/spaces/abc123/assets/hero.jpg?h=400

Returns the image at 400 px tall. Width scales proportionally.

Crop to exact dimensions

/api/v1/spaces/abc123/assets/hero.jpg?w=800&h=600

Returns a 800×600 image using cover crop — the image is scaled to fill the box and excess edges are trimmed. Use this for fixed-size slots like thumbnails or hero banners.

Convert to WebP with quality control

/api/v1/spaces/abc123/assets/product.png?f=webp&q=75

Converts a PNG to WebP at 75% quality. Typical file size reduction: 25–40% compared to the original PNG.

Responsive thumbnail

/api/v1/spaces/abc123/assets/blog-cover.jpg?w=400&f=webp&q=80

A compact, web-optimized version of a full-size image — suitable for article cards and preview grids.

Using Transforms in Code

@localess/client

Build the transform URL by appending parameters to the result of assetLink():

import { localessClient } from '@localess/client';

const client = localessClient({ spaceId: 'abc123', baseUrl: 'https://my-space.web.app' });

// Base CDN URL
const url = client.assetLink(content.data.heroImage);
// → https://my-space.web.app/api/v1/spaces/abc123/assets/hero.jpg

// With transform
const optimized = `${url}?w=1200&f=webp&q=80`;

@localess/react

import { resolveAsset } from '@localess/react';

function HeroImage({ image }: { image: ContentAsset }) {
  const baseUrl = resolveAsset(image);
  return (
    <img
      src={`${baseUrl}?w=1200&f=webp&q=80`}
      srcSet={[
        `${baseUrl}?w=400&f=webp&q=80 400w`,
        `${baseUrl}?w=800&f=webp&q=80 800w`,
        `${baseUrl}?w=1200&f=webp&q=80 1200w`,
      ].join(', ')}
      sizes="(max-width: 768px) 100vw, 1200px"
      alt={image.alt ?? ''}
    />
  );
}

@localess/angular — automatic with NgOptimizedImage

When you use provideLocalessBrowser(), Angular's NgOptimizedImage (ngSrc) directive automatically appends ?w=<requested-width> to the asset URL based on the width attribute. No manual parameter construction is needed:

<img
  ngSrc="{{ data.image | llAsset }}"
  width="800"
  height="600"
  alt="Hero image"
/>
<!-- Rendered src: https://my-space.web.app/api/v1/spaces/abc123/assets/hero.jpg?w=800 -->

URL Transforms vs Uploading Pre-Sized Assets

For most editorial content (blog images, product photos, hero banners) URL transforms are the right default. Upload the highest-quality version of an image once, then let Localess handle resizing and format conversion at request time.

Pre-sized uploads make sense for:

• Art-directed crops (different composition at mobile vs desktop)
• Images where the original quality must be preserved exactly (print, legal documents)
• SVG and other vector formats that do not benefit from raster transforms

Format Recommendations

Check browser support for your target audience before relying on WebP or AVIF exclusively. For broad compatibility, serve AVIF with a WebP and JPEG fallback using <picture> and <source>.