Image Picker
import "@taprootio/espalier/image-picker";
<esp-image-picker>
A form-associated image picker with large image choices and a selected preview.
The component is controlled: set images and value from consumer state,
then use esp-value-changed to persist a user's next selection. An empty
value means the Automatic choice. Labels are optional; unlabeled images use
their alternative text or a numbered name. Images are shown without cropping.
The large preview sits above the control by default. Set
preview-placement="beside" for a compact preview beside the control.
Size the preview and option images with the CSS properties below.
Attributes
<esp-image-picker> has the following attributes:
images
images has a default value of [].
Image candidates, kept in the supplied order.
value
value has a default value of "".
Selected image ID. An empty string selects Automatic.
preview-placement
preview-placement has a default value of "above".
Preview placement: above (default, large) or beside (compact).
disabled
disabled has a default value of false.
Disables the picker trigger.
loading
loading has a default value of false.
Shows a loading state while candidates are being fetched.
empty-message
empty-message has a default value of "No images available.".
Message shown when no image candidates are available.
automatic-label
automatic-label has a default value of "Automatic".
Label for the empty-value choice.
name
name has a default value of "".
The name used when this picker participates in a <form>.
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-picker> has the following methods:
focus
Focus the composed picker trigger.
validate
Re-run form validation.
checkValidity
Check form validity.
formResetCallback
Called by the browser when the owning form resets.
formStateRestoreCallback
Called by the browser when form state is restored.
formDisabledCallback
Called by the browser when an ancestor fieldset changes disabled state.
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-picker> emits the following events:
esp-value-changed
esp-value-changed is of type CustomEvent<string>.
Fired when a user chooses an image or Automatic. The detail is the selected image ID, or an empty string for Automatic.
esp-validity-changed
esp-validity-changed is of type CustomEvent<{ valid: boolean; message: string }>.
Fired whenever form validation runs.
CSS Properties
<esp-image-picker> has the following CSS properties:
--esp-image-picker-preview-height
Height of the large preview above the control. Default 16rem.
--esp-image-picker-option-width
Width of dropdown images, capped at 40vw on narrow screens. Default 12rem.
--esp-image-picker-option-height
Height of dropdown images. Images retain their aspect ratio. Default 8rem.
--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).