Waterfall for Craft CMS
Configuration
Profiles
A profile is one watermark: what it is, how big, where it goes, how see-through, and which images get it. Profiles are stored in project config, so they deploy with the site like a section or a field.
Lite allows one profile. Pro allows any number, and applies every one that matches — so a corner logo and a tiled copyright line can sit on the same image.
The mark
An image. Any asset. A PNG with transparency is what you want; a JPEG works but brings its own white box with it. The asset is referenced by UID, so renaming or moving the file later does not break the profile.
Text (Pro). Rendered as an object template, which means it can carry the asset and the site with it:
© {{ now|date('Y') }} {{ siteName }} — {{ asset.title }}
asset is the image being watermarked, siteName is the current site. Anything else Craft exposes
to an object template works too. A template that throws — a typo, a field this asset does not have
— falls back to the literal text rather than aborting the upload that triggered it.
Four fonts are bundled: Lato, Lato Bold, IBM Plex Mono and EB Garamond, all under
the SIL Open Font License. A profile can also point at an uploaded .ttf or .otf asset, which
wins over the bundled choice — that is how you use a brand typeface. Craft's
allowedFileExtensions does not include font files by default, so add ttf and otf to it before
uploading one.
Size
| Mode | What the percentage means |
|---|---|
| Percentage of the image width | The mark is that fraction of the base image's width |
| Percentage of the image height | …of its height |
| Fit inside a percentage box | Fits inside a box that fraction of both dimensions |
| Cover a percentage box | Covers it |
| Leave it at its own size | No scaling — the mark is used at its stored pixel size |
Scaling is always relative to the image being marked, never to the mark's own size, which is what makes one profile work on a 4000px original and a 400px thumbnail. Text is re-rendered at the computed size rather than rasterised small and scaled up, so it stays crisp.
Position
Nine anchors, plus tiled (Pro) and exact offset. Offsets are in pixels or as a percentage of the image, and they push away from the anchor's own edge: a bottom-right mark with a 2% offset sits 2% in from the right and 2% up from the bottom.
Tiling repeats the mark across the whole image with a gap you set as a percentage of the image. Tiles that overhang the edge are cropped, not skipped, so the pattern reaches the corners.
Appearance
- Opacity — 0–100.
- Rotation (Pro) — degrees. Rotated marks are drawn once and repeated, so a tiled diagonal watermark is one rotation, not one per tile.
- Blend mode (Pro, ImageMagick only) — multiply, screen, overlay, darken, lighten, difference, exclusion, hard light, soft light, colour dodge, colour burn. On a GD server the list shows only Normal rather than offering eleven modes that would all come out the same.
Which images get it
Every rule is an and. An asset has to pass all of them.
| Rule | Behaviour when left empty |
|---|---|
| Apply | Nothing happens at all — pick at least one of the three modes |
| Volumes | Every volume |
| Transforms | Every transform, including ones built from inline parameters |
| File types | Every type Craft can manipulate |
| Minimum width / height | No minimum |
| Only these assets (Pro) | No condition |
Transforms is a list of named transform handles. A transform built from inline parameters in a template has no handle and can never be named here, so it is covered only by profiles that name no transforms at all.
Only these assets is Craft's own asset condition — the same builder as an asset field's source settings — so anything Craft can filter on, a profile can be limited to.
Waterfall refuses some images whatever the rules say, and tells you which and why: vector files, animated GIFs (unless you switch that off), images below the profile's minimum, and file types Craft cannot manipulate.
Per-asset control (Pro)
Add the Waterfall field to an asset field layout and each asset gets three choices: follow the profiles, never watermark this one, or use specific profiles. It is how you exempt a supplier's image or a press-kit logo without weakening a rule that covers thousands of files.
Plugin settings
Settings → Plugins → Waterfall.
| Setting | Default | What it does |
|---|---|---|
| Watermark generated transforms | on | The master switch for transforms mode |
| Watermark new uploads | on | Applies permanent profiles as images arrive |
| Quality | 92 | Re-encoding quality for images Waterfall has marked |
| Keep originals in | Waterfall's storage folder | Filesystem for backups — see below |
| Store derivatives in | each volume's transform filesystem | Where on-demand derivatives are written |
| Derivative folder | _waterfall | Path prefix inside that filesystem |
| Skip animated GIFs | on | Re-encoding a GIF loses the animation |
| Queue above | 25 | Bulk runs larger than this go to the queue |
| Add watermarks to Imager-X transforms | on | Needs Imager-X Pro; see Usage |
Backups
permanent mode writes into the asset's own file, so the original is copied first. By default that
copy goes to storage/waterfall/originals, which is outside the web root and is not part of
the volume's own backups. On a single server that is fine. If your uploads live on S3 and your
storage folder does not survive a deploy, point Keep originals in at a real filesystem
instead.
The backup is taken once per asset, the first time it is marked. A second profile applied later does not overwrite it — otherwise the "original" would be the already-watermarked file, and restore would give you back a marked image.
Delivery services (Pro)
Credentials for imgix, Cloudinary, ImageKit and the URL template driver live on the same settings screen, and each can be an environment variable. None of them is needed to watermark on your own server. See Usage for what each service can and cannot do.