e8-image
Updated on Aug 14, 2025 5 minutes to readProvide an image (or icon) with optional preview and a mobile-friendly download action.
Overview
<e8-image> renders an image or an icon from different source types and handles loading state, responsive sizing, click‑to‑preview, and (optionally) a download button.
<e8-image
:source="object.file"
source-type="file"
:thumbnail-size="512"
width="320px"
height="200px"
radius="rounded"
:bordered="true"
alt="Product photo"
:show-download-button="true"
download-button-variant="primary"
/>Properties
| Property | Description | Type | Default |
|---|---|---|---|
| alt | Alternate text for accessibility and when the image fails to load. | string | — |
| bordered | Adds a border around the image. | boolean | false |
| disable-download-buttons-on-preview | Mobile-only preview option: when true, hides download/share actions inside the native preview. | boolean | false |
| download-button-variant | Variant applied to the download button. | enum "ButtonVariants" | primary |
| group | Logical group id for previewing multiple images in the same session. | string | — |
| height | Desired CSS height (e.g. '320px', '100%'). | string | — |
| icon-variant | For icon only: a icon color variant`. | enum "IconVariants" | — |
| img-class | Extra classes to apply to the <img> or the icon container. | string, string[], Record<string, boolean> | — |
| keep-aspect-ratio | When true and thumbnail-size is used, requests a thumbnail that preserves aspect ratio. Also affects how width/height are applied. | boolean | false |
| non-clickable | Disables all click behavior (no preview, no event dispatch). | boolean | false |
| radius | Corner rounding. | enum "RadiusVariants" | — |
| responsive | The image scales with its parent. | boolean | true |
| show-download-button | Shows a small overlay button for downloading/saving (hidden for icons and while loading). | boolean | false |
| source | The image source. Meaning depends on source-type. | string | — |
| source-type | Controls how source is interpreted. | enum "SourceTypes" | image |
| thumbnail-size | For file only: requested thumbnail size (px). When set, loads a thumbnail; otherwise loads the full file. | number | 50 |
| width | Desired CSS width (e.g. '320px', '100%'). | string | — |
Events
| Event | Description | Arguments |
|---|---|---|
| on-click | Emitted when the image is clicked. | — |
Source & Source Types
Set the source according to the chosen source-type:
image—sourceis an metadata image script alias.file—sourceis a file id; loads a thumbnail whenthumbnail-sizeis set, otherwise the file’s download URL.url—sourceis a direct HTTP(S) URL and will be loaded as-is.icon— renders<e8-icon :name="source">instead of an<img>.
Preview
When show-preview-on-click is true (default) and non-clickable is false, clicking the image opens a preview. If multiple images share the same group, they will be previewed together.
Mobile app: Set
disable-download-buttons-on-previewto hide download/share actions inside the mobile preview UI.
Sizing & Aspect Ratio
The component calculates styles based on width, height, the image’s natural size, and keep-aspect-ratio:
- When both
widthandheightare provided andkeep-aspect-ratioisfalse, the image uses those exact dimensions. - Otherwise, the longer side is constrained and the other side is set to
auto. If the natural size is known, it limits the displayed size tomin(100%, naturalPx). - For icons (
icon), ifheightis set, the icon’sfont-sizeis \~75% of that height, keeping the visual box aligned.
Download Button
When show-download-button is true (and the source is not an icon), an overlay button appears in the bottom-right corner.
Its style is controlled by download-button-variant.
Mobile app: The image is saved to the device’s photo gallery.
Click Behavior
- If
non-clickableistrue, clicks are ignored. - If
on-clickis set, the component invokes the event before opening the preview.
Types
| Type | Description |
|---|---|
| enum "RadiusVariants" | One of none, rounded, or circled. |
| enum "SourceTypes" | One of image, file, url, or icon. |