Image Transforms

Resize, reformat, and optimize images on demand by appending URL parameters to any Localess asset URL — no extra service required.

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().

Parameter	Type	Description	Example
`w`	integer (pixels)	Target width. The image is scaled to this width. Height adjusts proportionally unless `h` is also set	`?w=800`
`h`	integer (pixels)	Target height. The image is scaled to this height. Width adjusts proportionally unless `w` is also set	`?h=600`
`q`	integer (1–100)	Output quality for lossy formats (JPEG, WebP). Higher is better quality; lower is smaller file. Default: `85`	`?q=70`
`f`	string	Output format. Supported values: `webp`, `jpeg`, `png`. Defaults to the original format	`?f=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.

Constrain both dimensions (fit within a box)

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

The image fits within a 800×600 bounding box. Aspect ratio is preserved — neither dimension will exceed the specified value.

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

Approach	Best when
URL transforms	You upload once and serve at multiple sizes — responsive images, thumbnails, format variants
Pre-sized uploads	You need pixel-perfect control over cropping, or you have assets that are already optimized at a fixed size (icons, logos, print-ready images)

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

Source format	Recommended `?f=` value	Reason
JPEG	`webp`	25–35% smaller at equivalent quality
PNG (photographic)	`webp`	Better compression than PNG for photos
PNG (transparency needed)	`png` or `webp`	WebP supports alpha — prefer WebP for modern browsers
Already WebP	—	No conversion needed

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

On this page