Watermarking
Image watermarking
Overlay your logo or badge on every image served through a CDN domain. The watermark is applied at the edge and cached like any other variant, with no changes to your origin files.
On this page5 sections
How it works#
Watermarking is configured per domain and applied automatically. There are no URL parameters to add. When an image is fetched from your origin and processed at the edge, the watermark is composited onto it before the result is cached. Subsequent requests serve the watermarked image straight from cache.
- Upload a watermark image (PNG or WebP with transparency, up to 1 MB) in your domain’s settings.
- Choose position, size, opacity and margins.
- Every image served through the domain is watermarked from then on.
Settings#
| Setting | Description | Default |
|---|---|---|
| Position | 9-point grid: corners, edges, or centre | bottom-right |
| Size | Watermark width as a percentage of the output image width (1–50%) | 15% |
| Opacity | 0–100% | 60% |
| Margin | Distance from the image edges in pixels | 16px |
| Minimum width | Images narrower than this are served without a watermark (thumbnails, placeholders) | 200px |
Behaviour notes#
- Works with transforms: the watermark is applied after resizing and effects, so it scales correctly with
?width=and other image optimisation parameters. Each transform variant is watermarked and cached independently. Animated GIFs are watermarked on every frame. - Cache updates are automatic: changing the watermark image or its settings automatically applies to images as they are next requested. No purge is required. Enabling watermarking on a busy domain causes a one-time re-cache of image variants.
- Availability first: if the watermark asset is temporarily unavailable, images are served unwatermarked rather than failing. Watermarking never blocks delivery.
- Placeholders are excluded: LQIP placeholders and images below the minimum width are never watermarked. A logo on a 20px blur preview helps nobody.
Best practices#
- Use a PNG or WebP with a transparent background. Solid backgrounds look like a sticker.
- Upload at roughly 2× the largest size it will render (e.g. a 600px-wide logo file for a 15% overlay on 2000px images) so it stays crisp.
- 60–70% opacity marks images clearly without ruining them. Use 100% only for hard branding.
- Keep the minimum-width threshold at or above your thumbnail size so grids stay clean.
Next steps
Something unclear or out of date? Tell us