ImageUpload¶
ImageUpload is a single-file field with image selection and confirmation. It inherits File data binding, file-name and revision attributes, template sources, required validation, and editing settings. Its default picker filter is image/*; an explicit Accept can narrow selection, but the widget still requires an image.
1 | |
The bound data remains a scalar file ID. Use FileList for multiple file references.
Preview and Confirmation¶
Local selection, drop, paste, and camera capture open Review Image before upload. Use Image accepts the result; cancelling leaves the existing form value unchanged and does not start the local upload. Recently used files, templates, and cloud results also require a confirmation preview. Stored or external results are preview-only; their bytes are not fetched into the local crop editor.
For local JPEG and static PNG images, the review window provides 90-degree rotation, percentage crop boundaries, reset, and pixel dimensions. Crop boundaries apply after rotation. The editor uses standard theme controls in a dialog, keeping the form field compact.
An existing form image opens a preview through its file name. If that image cannot load, an explanation appears and the file-opening link remains available.
Compression¶
Compression is optional and defaults to None. Presets preserve proportions and do not upscale an image.
| Preset | Automatic processing |
|---|---|
None | Keep the selected bytes without automatic resizing or recompression. |
Document | Fit JPEG or static PNG within a 2000-pixel long edge. |
Web | Fit JPEG or static PNG within a 1280-pixel long edge. |
EMail | Fit JPEG or static PNG within an 800-pixel long edge. |
KeepRatio | Keep original dimensions; try JPEG encoding at 85% quality. Other formats remain unchanged. |
JPEG processing uses 85% encoding quality. PNG resizing keeps PNG format and transparency. If automatic processing produces a larger file, the selected file is retained. When the user has explicitly cropped or rotated the picture, this comparison uses the edited file, so the edit is preserved. JPEG edits also require re-encoding even with None.
GIF, WebP, SVG, animated PNG, and other formats are not automatically converted or offered local crop/rotation controls. PNG files whose initial metadata cannot establish that they are static are also preserved. They still need to be previewable by the browser to be accepted by this field.
KeepRatio preserves dimensions; it is not a 2000-pixel resize preset. Use Document when that bound is required.
Validation and Permissions¶
The client rejects images larger than 50 MiB (50 * 1024 * 1024 bytes) or 40 million pixels, as well as images it cannot decode. Known raster headers are checked before decoding when available, and decoded dimensions are checked again. Remote preview size is checked when size metadata is available. Image loading times out after 15 seconds.
These checks are client safeguards, not server-side authorization or content validation. The upload endpoint's file policies and file read/write permissions remain authoritative. Template and external-link selection do not grant access beyond the current user's permissions.