Image Upload
import "@taprootio/espalier/image-upload";
<esp-image-upload>
Used to upload images.
Uploading new images
The esp-image-upload-file-selected event detail provides the image
reference (the actual object in uploadedImages) plus
onProgress, onComplete, and onFailed callbacks
bound to it, and a signal that aborts if the user removes
the image while it is still uploading. The same shape is
used for esp-image-upload-retry.
Simulated upload progress demo
Select images to see simulated progress. The second file will fail — click Retry to re-upload it.
Editing with existing images
Pre-populate with server images via setExistingImages.
Existing images never show upload overlays.
Attributes
<esp-image-upload> has the following attributes:
accept
accept has a default value of "image/jpeg, image/png, image/webp".
Comma-separated list of accepted file types, in the same format as the
native input accept attribute: MIME types (image/png), MIME
wildcards (image/*), or extensions (.png). Files outside this list
are skipped and reported via the esp-image-upload-files-rejected event.
max-images-per-row
max-images-per-row has a default value of undefined.
Maximum number of image previews in each justified row. Positive integers create a hard row boundary; omitted, non-finite, non-integer, and nonpositive values leave rows unlimited.
max-row-height-vh
max-row-height-vh has a default value of DEFAULT_ALBUM_MAX_ROW_HEIGHT_VH.
Maximum preview-row height as a percentage of the layout viewport. Values
outside the inclusive integer range 1…100 fall back to 90.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-image-upload> has the following methods:
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-image-upload> emits the following events:
esp-image-upload-file-removed
esp-image-upload-file-removed is of type CustomEvent<EspalierUploadImage>.
Fired when an image has been removed by the user. Narrow on detail.source to distinguish newly selected images from pre-existing server images. If the image's upload was still in flight, its signal aborts.
esp-image-upload-file-selected
esp-image-upload-file-selected is of type CustomEvent<UploadEventDetail>.
Fired when an image has been selected by the user. detail.image is the actual object stored in uploadedImages; detail.onProgress, detail.onComplete, and detail.onFailed are callbacks bound to that image. detail.signal aborts if the image is removed mid-upload — pass it to fetch/XHR.
esp-image-upload-retry
esp-image-upload-retry is of type CustomEvent<UploadEventDetail>.
Fired when the user clicks Retry on a failed upload. detail.image is the same object reference; fresh callbacks and a fresh signal are provided. The component automatically resets the image to indeterminate progress.
esp-image-upload-images-reordered
esp-image-upload-images-reordered is of type CustomEvent<ImagesReorderedDetail>.
Fired after the user drags an image to a new position. detail.images is the reordered array (same references, new order).
esp-image-upload-files-rejected
esp-image-upload-files-rejected is of type CustomEvent<FilesRejectedDetail>.
Fired when selected files are skipped, either because their type is not accepted (detail.unsupported) or because they could not be read or decoded (detail.unreadable). The component also shows a transient inline notice.
CSS Properties
<esp-image-upload> has the following CSS properties:
--esp-image-upload-preview-background
The background color of the image preview area.
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).