Preparing images before you upload them

A slow website is usually a website with big pictures on it. ClickWhale does a lot of the work for you. It resizes and crops every image before a visitor downloads it, but there are two things it doesn't do, and they're the two that cost the most. Get those right before the file reaches the media library.

Save photographs as JPEG. No wider than about 2000 pixels, and aim for under 500 KB each.

What ClickWhale does for you

When a visitor loads a page with an Image element on it, they don't get your original file. ClickWhale makes a copy at the size the element asks for, crops it to the chosen ratio, caches it, and serves that. The same happens for the photo slider and the photo gallery.

Two settings on the element control it:

• Image size: the maximum width of the delivered copy, from 320 to 2560 pixels. The default is 480.
• Image ratio: the shape it's cropped to. The default is 16:9.

So an Image element set to 480 wide never sends a visitor more than a 480-pixel-wide picture, however big your original is. That is why the media library's 20 MB limit isn't the real constraint.

Two things about the crop:

• It crops from the centre. If the subject of your photo is near an edge, the crop will cut it. Crop the photo yourself before uploading if the composition matters.
• It only ever scales down. Asking for 2560 from an 800-pixel original gives you 800 pixels, stretched to fit and looking soft. The size setting is a ceiling, not a target. The sharpness has to be in the file you upload.

What ClickWhale doesn't do

It doesn't change the format. A PNG stays a PNG at every size, a JPEG stays a JPEG. This is the single biggest avoidable weight on a ClickWhale site.

PNG is a lossless format. It's the right choice for a logo, a diagram, an icon, or anything with flat colour and sharp edges. It is the wrong choice for a photograph: a photo saved as PNG is routinely five to ten times the size of the same photo as a JPEG, and it stays that way at every size ClickWhale delivers, because the format is never converted.

It doesn't compress beyond the resize. If your original is a lightly-compressed 8 MB export, the 480-pixel copy is smaller but still fatter than it needs to be.

So the work you do before uploading is: pick the right format, and export at a sensible quality.

Choosing a format

AVIF is not supported. Neither is HEIC, which is what iPhones save by default. Export or convert to JPEG first.

Dimensions

Work out how wide the image will actually be on screen, then upload something around twice that for sharpness on high-resolution displays, and no more.

There is no benefit to uploading a 6000-pixel camera original. ClickWhale will never send it to anyone; it just sits in your media library taking up room and slowing your own uploads.

A 6 MB phone photo in a 400-pixel slot isn't slow for your visitors. ClickWhale resizes it, but it is slow to upload, slow to work with, and it fails the 20 MB limit as soon as someone tries a burst of them. Resize before you upload.

File size

• Photographs: under 500 KB each. Most look identical at 200–300 KB.
• Logos and icons: under 50 KB, or an SVG.
• A whole page: if the images on one page add up to more than about 1.5 MB as delivered, look again at the biggest one.

You can check what's actually being delivered: open the live page, right-click an image and open it in a new tab. The address will show the width ClickWhale served it at.

Upload limits

Two things about how uploads are checked:

• The file type is read from the file's contents, not its name. Renaming photo.heic to photo.jpg does not make it uploadable. ClickWhale looks inside and rejects it.
• An image containing scripts is refused. SVG files can carry executable markup, so any image with a script or an inline event handler in it is rejected as unsafe. If a logo from a designer won't upload, this is usually why; re-export it from the drawing program rather than editing the file.

Replacing an image later

Uploading a file whose name matches an existing one overwrites it, but the resized copies are not regenerated. The old picture keeps appearing, sometimes for a long time, because the copy the site serves is cached under the image's address.

So for anything you'll replace regularly, either upload under a new name and repoint the element, or (for a document rather than an image) use a short file address, which can be pointed at a new file without touching anything that references it. See Short addresses for files and The media library.

Common issues