Images are heavy. A product catalog with five thousand items and full-resolution photos is a spectacular way to destroy page-load times, mobile data plans, and user patience. An image in an email that arrives at several megabytes is why people block images in email by default. A gallery that loads every picture at full size is the kind of detail that makes a platform feel unprofessional regardless of how good the rest of it is. The work of handling images well — thumbnails, compression, lightboxes, original-filename preservation, sensible defaults — is exactly the kind of work most implementers don't want to rebuild for every type they add. So we don't make them.
Automatic thumbnails are generated the moment an image is uploaded. The moment the upload completes, a thumbnail is queued and created in the background; by the time the next user loads the record, the thumbnail is ready. Tables, lists, cards, and kanban boards use the thumbnail rather than the full image, which means a page showing thirty records with thumbnails loads almost as fast as a page showing thirty records with text. For a product catalog, a team directory, or any other image-heavy view, this is the difference between usable and not.
Per-property thumbnail width adds the control that matters when "thumbnail" isn't one size. A product-image property might use smaller thumbnails to fit more items on screen; a team-photo property might use larger ones because team photos are the point of the view. The width is set per property, which means different types can make different choices and each gets the inline thumbnail size that actually fits its usage. There's no single platform-wide size anyone has to argue about.
Click a thumbnail to open a lightbox is the expected next interaction. The full-size image opens in an overlay; users can zoom, pan, and navigate to neighboring images without leaving the page they were on. The lightbox is consistent wherever images appear — tables, cards, canvas blocks, rich-text content — so users learn the interaction once. That consistency matters more than any particular lightbox feature: the expected interaction always works.
Lightbox sets take the behavior a step further. Images grouped in a canvas page — a set of product photos on a product-detail page, a gallery of before-and-after photos on a case study, a timeline of project progress photos on a project dashboard — share a single lightbox navigation. Open one image and the forward and back arrows move through the whole group. That's how a gallery actually feels like a gallery, rather than a grid of independent thumbnails that each need to be clicked individually.
Image compression on upload keeps file sizes sane. The compression level is configurable per tenant and per property, so an image library that cares about pixel-level fidelity (archival photos, design assets) can use lighter compression while a general-purpose image field (profile photos, thumbnail headers, attachment previews) uses heavier compression to keep storage and bandwidth costs down. The original is preserved where the configuration calls for it; the compressed version is what's served to most surfaces. Users see fast-loading pages; operators see manageable storage bills.
Original filename preservation is a small feature with a big payoff over time. When a user uploads "Q3-2024-final.jpg," the name "Q3-2024-final.jpg" is what they — and everyone else who sees the image later — will see associated with it. The platform stores files under an internal identifier for robustness, but the original filename is kept as metadata and surfaces everywhere a filename makes sense: in exports, in downloads, in email attachments, in the file repository. Files don't lose their human-meaningful names on the way in.
Multiple images on one field are handled naturally. A property that accepts several images shows them as an ordered gallery; users drag to sort the order; each image gets its own lightbox behavior within the group. That's the right shape for most real-world "attach a few photos" workflows, from real-estate listings with eight property photos to incident reports with a handful of supporting images.
Canvas-block image rendering gives implementers more control where needed. An image property displayed in a canvas block can be configured with its own lightbox behavior, link behavior, and default width — "auto" is a sensible default that respects the image's natural size within the page layout, but specific widths are supported for grid-style presentations. Canvas image blocks participate in lightbox sets, so galleries built in canvas get the group-navigation behavior without additional configuration.
PDF export of images is covered in the PDF generation article, but worth a brief mention here: images in records and in canvas pages carry through to PDF output, with the platform handling the path from on-screen rendering to print-ready embed. For implementations that generate documents heavy with product images, branded graphics, or documentary photos, that handoff matters.
The cumulative effect of these features is that implementations don't have to think about images as a separate problem. Add an image property to a type; everything that follows — the uploads, the thumbnails, the lightboxes, the compression, the downloads, the exports — just works. That's the shape the platform is meant to take for every feature category: foundational infrastructure that gets the boring parts right, so implementers can focus on the parts where their judgment actually adds value.
Image erasure, where users need to remove an image permanently from a record, is supported and respects the audit trail — the fact that an image existed and was removed is captured, even when the underlying file is gone. For privacy-sensitive workflows (personnel photos, regulated-industry records), that combination of clean removal and audited history is what keeps the feature usable without being a compliance problem.
For any implementation that includes user-visible images at any scale — which is most of them — the handling layer is one of those quiet features that determines how the product feels. We treat it as foundational, and the details show it.