e8-form-image
Updated on Sep 18, 2025 7 minutes to readA single image upload and preview component with optional image manipulation and management.
Overview
e8-form-image allows users to upload, view, download, edit, or remove a single image.
It supports drag-and-drop and manual file selection, thumbnail previews, and configurable image manipulation options such as resizing, format conversion, and compression.
<e8-form-image
v-model="vars.avatar"
owner-script-alias="lstUsers"
attr-script-alias="avatar"
label="Profile Picture"
tooltip="Upload your avatar"
group="userImages"
:thumbnail-size="120"
:keep-aspect-ratio="true"
:save-option-width="800"
:save-option-height="600"
save-option-format="JPEG"
:save-option-compress="80"
:max-image-size="2048"
></e8-form-image>Properties
| Property | Description | Type | Default |
|---|---|---|---|
| accept | Comma-separated list of accepted MIME types or extensions (e.g. "image/png,image/jpeg"). | string | 'image/*' |
| alt | Alt text for the image. | string | '' |
| attr-script-alias | Attribute alias for resolving the upload URL. | E8ScriptAlias | — |
| deletion-confirmation | Enables confirmation prompt before image removal. | boolean | true |
| downloading-disabled | Disables image download. | boolean | false |
| editing-disabled | Disables image editing. | boolean | false |
| group | Group name for image gallery. | string | '' |
| keep-aspect-ratio | Maintains original image aspect ratio when resizing. | boolean | false |
| label | Custom label text; set to false to hide label. | string | boolean | — |
| max-image-size | Maximum image size (in KB). | number | string | — |
| modify-data | Determines whether changes to this field mark the object as modified and require saving. | boolean | true |
| owner-script-alias | Owner alias for resolving the upload URL. | E8ScriptAlias | — |
| readonly | Disables upload, edit, and delete actions. | boolean | false |
| removing-disabled | Disables image removal. | boolean | false |
| save-option-compress | Compression level (0–100) for image upload. | number | 100 |
| save-option-format | Output image format. | E8FileManipulationImageFormats | — |
| save-option-height | Target height in pixels for image uploads. | number | — |
| save-option-width | Target width in pixels for image uploads. | number | — |
| show-checker | Displays a checkerboard background beneath all images to indicate transparency. | boolean | false |
| thumbnail-size | Size of the thumbnail preview in pixels. | number | 80 |
| tooltip | Tooltip text displayed below the input. | string | — |
| v-model | Two-way bound image file identifier. | string | — |
| viewing-disabled | Disables image preview. | boolean | false |
Slots
| Slot | Description |
|---|---|
| label | Custom label slot. Provides { label, value } as slot props. |
Events
| Event | Description |
|---|---|
| on-change | Emitted when the image value changes. |
Properties Details
Max image size
Maximum target file size in KB.
When this option is set, the image processing logic uses it as the file-size target. It also defines default target
dimensions internally. Smaller max-image-size values produce smaller default target dimensions.
max-image-size does not disable save-option-width or save-option-height.
Save option compress
Target compression quality.
The default value is 100, which means no additional quality reduction.
Values are normalized before processing:
80means80%quality0.8also means80%quality100means100%quality
Compression quality is applied only to formats that support quality compression, such as JPEG and WEBP.
For PNG, this option does not reduce quality.
Save option format
Target image format.
When this option is set, the uploaded image is converted to this format if it is not already in that format.
An empty value means "keep the source format when possible".
Save option height
Maximum target image height in pixels.
If the uploaded image is taller than this value, it is resized down proportionally.
If the image is already shorter than this value, it is not enlarged.
Save option width
Maximum target image width in pixels.
If the uploaded image is wider than this value, it is resized down proportionally.
If the image is already narrower than this value, it is not enlarged.
Application Order
Image options are collected from component props in this order:
max-image-sizesave-option-formatsave-option-widthsave-option-heightsave-option-compress
After that, the image processing logic decides whether the uploaded image must be changed.
The image is processed if at least one of these conditions is true:
- the file is larger than
max-image-size - the image width is larger than
save-option-width - the image height is larger than
save-option-height save-option-formatis set and the current format is differentsave-option-compressis less than100for a compressible format- at least one image resize option is set and the source image format is not supported
Dimension Rules
save-option-width and save-option-height are always respected when they are set.
This means that an image can still be resized even when it is already smaller than max-image-size by file size.
<!-- If the uploaded image is `300 KB` but `2000 px` wide, it is still resized because its width is larger than `1200 px`. -->
<e8-form-image
:max-image-size="500"
:save-option-width="1200"
/>max-image-size And Dimensions
When max-image-size is set, default target dimensions are chosen automatically.
If save-option-width or save-option-height is also set, the explicit component prop overrides the automatically chosen
dimension.
<e8-form-image
:max-image-size="500"
:save-option-width="800"
/>In this case:
max-image-sizestill defines the target file sizesave-option-widthexplicitly defines the target width- the automatic width from
max-image-sizeis not used - the automatic height from
max-image-sizeis still used unlesssave-option-heightis also set
Format Rules
If save-option-format is set, it has priority over the source image format.
If save-option-format is empty, the original format is kept when it is supported.
If the original format is not supported, it is converted to a supported image format only when at least one image resize option is set.
Compression Rules
If only save-option-compress is set, the image is saved with the requested quality.
If both max-image-size and save-option-compress are set, compression starts from the requested quality
PNG Rule
PNG does not use quality compression.
The image is converted to PNG, but save-option-compress does not reduce PNG quality.
PNG can still be resized by save-option-width, save-option-height, or dimensions derived from max-image-size.