导航|地址|刷新
Draw overlays and watermarks

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/images/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Cloudflare Images

/

Overview

Get started

Introduction

Key concepts

Limits and formats

Optimization

Features

Remote images (transformations)

Overview

Define source origins

Create transformation flows

Transform via fetch

Control origin access

Draw overlays and watermarks

Integrate with frameworks

Set up rewrite rules

Preserve Content Credentials

Hosted images

Serve uploaded images

Create predefined variants

Enable flexible variants

Apply blur

Delete variants

Preserve Content Credentials

Browser TTL

Serve images from custom domains

Serve private images

Optimize with Workers

Draw overlays and watermarks

Make responsive images

Storage

Upload images

Methods

Upload via URL

Upload via custom path

Accept user-uploaded images

Upload via batch API

Upload via a Worker

Upload via Sourcing Kit

Overview

Enable Sourcing Kit

Edit sources

Credentials

Configure webhooks

Manage hosted images

Edit images

Export images

Delete images

Manage with Workers

Demos and architectures

Pricing

Cloudflare Polish

Overview

Activate Polish

Polish compression

Cf-Polished statuses

WebP may be skipped

Images API Reference ↗API

Reference

Troubleshooting

Security

Tutorials

Optimize mobile viewing

Transform user-uploaded images before uploading to R2

Examples

Platform

Changelog

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Cloudflare Images llms.txt ↗

Cloudflare Images llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Cloudflare Images

/Optimization

/Draw overlays and watermarks

Draw overlays and watermarks

Last updated Jun 16, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewDraw with cf.imageDraw with the Images bindingOptions url width and height repeat top, left, bottom, right opacity compositeExamples Watermark Logo in the corner Multiple overlays Rounded corners

Use Workers to draw watermarks, logos, signatures over other images. Overlays support transparency, positioning, and compositing modes.

You can draw overlays in a Worker using two approaches:

cf.image on a fetch subrequest — Add a draw array to the image options. All images must be accessible via URL. Use this approach when optimizing images through the URL interface.

Images binding — Chain .draw() calls when overlaying images from any source, including hosted images or R2.

Draw with cf.image

To draw overlays on a fetch() subrequest in Workers, you can add a draw array to your cf.image options.

Each entry in the array specifies an overlay and its options, including optimization parameters like width, height, fit, blur, and rotate. Overlays are drawn in the order they appear — the last entry is the topmost layer.
export default { async fetch(request) { const imageURL = "https://example.com/image.png"; return fetch(imageURL, { cf: { image: { width: 800, height: 600, draw: [ { url: "https://example.com/branding/logo.png", bottom: 5, right: 5, fit: "contain", width: 100, height: 50, opacity: 0.8, }, ], }, }, }); },};

Draw with the Images binding

The Images binding uses a chainable .draw() method to draw an overlay on top of an image. You can chain multiple .draw() calls for multiple overlays.

Pass the overlay image as the first argument, then the draw options as the second. To apply optimization parameters to the overlay image, pass an .input() chain with .transform() as the first argument.
export default { async fetch(request, env) { const img = await fetch("https://zzzdna.com/blue.png"); const watermark = await fetch("https://zzzdna.com/purple.png"); const response = ( await env.IMAGES .input(img.body) .draw( env.IMAGES.input(watermark.body).transform({ width: 100 }), { bottom: 10, right: 10, opacity: 0.5 } ) .output({ format: "image/avif" }) ).response(); return response; },};

Options

The dimensions of the output image are always determined by the base image. The overlay is then drawn onto the base image's canvas.

The following draw-specific options can be used for positioning and blending.

url

Absolute URL of the overlay image when drawing with cf.image. Supports any supported image format. For watermarks or non-rectangular overlays, use PNG or WebP images.

When drawing with the Images binding, the overlay is passed as image bytes or an .input() chain instead of a URL. Refer to Draw with the Images binding.

width and height

Sets the maximum dimensions of the overlay image when drawing with cf.image. Accepts an integer (pixels) or a decimal between 0 and 1 representing a fraction of the base image's dimension. For example, height:0.25 sets the overlay height to 25% of the height of the base image.

Use fit and gravity to control how the overlay image is resized and cropped.

When drawing with the Images binding, the dimensions of the overlay image can be set using the .transform() method.

repeat

Determines whether to tile the overlay across the image.

Accepts the following values:

true — Tiles the overlay to cover the entire area. This is useful for watermarks.

x — Tiles the overlay horizontally only.

y — Tiles the overlay vertically only.

top, left, bottom, right

Sets the position of the overlay image as an offset, in pixels, to the specified edge. 0 aligns the overlay flush to the edge. If no position is specified, then the overlay is centered.

For example, { bottom: 0, right: 10 } places the overlay at the bottom-right corner, 10 pixels inward from the right edge.

Setting both left and right, or both top and bottom returns an error.

opacity

Sets the opacity of the overlay image. Accepts a decimal value between 0.0 (fully transparent) and 1.0 (fully opaque). For example, opacity: 0.5 makes the overlay semitransparent.

composite

Controls how the overlay is blended with the base image using Porter-Duff compositing operations ↗. The default is over.

The composite mode only affects the area within the overlay's bounding box. The base image is always preserved outside of this area.

Accepts the following values:

over

Draws the overlay image on top of the base image. This is the default composite behavior.

The overlay covers the base where they overlap. Both images are visible where they do not overlap.

in

Shows the overlay only where the base image is opaque. If the overlay has transparent pixels that overlap with the base image, then those areas of the base image will also become transparent.

atop

Draws the overlay image on top of the base image, but only where the base image is opaque. This will clip the overlay image to the shape of the base image.

If the overlay has transparent pixels that overlap with the base image, then the base image remains visible (unlike in).

out

Shows the overlay only where the base image is transparent. Within the overlay's bounding box, opaque areas of the base image will become transparent.

xor

Shows the areas of each image where the other is transparent. Overlapping opaque areas will become transparent. This can be used to create rounded corners or custom shapes.

lighter

Adds the color values of both images, which makes the overlapping areas brighter.

Examples

Watermark

Tile a semitransparent watermark across the entire image using cf.image.
fetch(imageURL, { cf: { image: { draw: [ { url: "https://example.com/watermark.png", repeat: true, opacity: 0.2, }, ], }, },});

Logo in the corner

Position a logo at the bottom-right corner using cf.image.
fetch(imageURL, { cf: { image: { draw: [ { url: "https://example.com/logo.png", bottom: 5, right: 5, }, ], }, },});

Multiple overlays

Combine multiple overlays in one request using cf.image. They are drawn in order — the last entry is the topmost layer.
fetch(imageURL, { cf: { image: { draw: [ { url: "https://example.com/watermark.png", repeat: true, opacity: 0.2 }, { url: "https://example.com/play-button.png" }, { url: "https://example.com/logo.png", bottom: 5, right: 5 }, ], }, },});

Rounded corners

Cut rounded corners from an image. A corner mask is drawn at each corner and rotated to match the position. xor removes the overlapping pixels.

The example below shows how this can be done using the Images binding.
const image = await fetch("https://example.com/photo.png");const mask = await fetch("https://example.com/corner-mask.png");let [topLeft, topRight] = mask.body.tee();let bottomLeft, bottomRight;[topLeft, bottomLeft] = topLeft.tee();[topLeft, bottomRight] = topLeft.tee();const output = await env.IMAGES .input(image.body) .draw(env.IMAGES.input(topLeft).transform({ rotate: 0 }), { left: 0, top: 0, composite: "xor", }) .draw(env.IMAGES.input(topRight).transform({ rotate: 90 }), { right: 0, top: 0, composite: "xor", }) .draw(env.IMAGES.input(bottomRight).transform({ rotate: 180 }), { bottom: 0, right: 0, composite: "xor", }) .draw(env.IMAGES.input(bottomLeft).transform({ rotate: 270 }), { bottom: 0, left: 0, composite: "xor", }) .output({ format: "image/png" });return output.response();

PreviousOptimize with WorkersNextMake responsive images

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Draw with cf.image

Draw with the Images binding

Options

url

width and height

repeat

top, left, bottom, right

opacity

composite

Examples

Watermark

Logo in the corner

Multiple overlays

Rounded corners

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices

Docs

------
导航页打开网址