Image
Optimized image component for local and remote sources.
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Dunedin Cliff" source="/src/assets/images/component-docs/dunedin-cliff.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/dunedin-cliff.jpg
alt: Dunedin Cliff
rounded: false
---Overview #
An image component with built-in optimization for local, CDN, and remote sources. Automatically serves responsive sizes and modern formats like AVIF for smaller file sizes. Supports aspect ratios, object fit, positioning, rounded corners, and automatic cropping when aspect ratios are set.
Properties #
source string | default: /src/assets/images/placeholder.png
The URL or path to the image.
alternateSource string
Optional alternate image shown when the site theme is toggled. The main source is shown by default.
alt string
Alternative text for accessibility.
sizes string | default: (max-width: 1280px) 100vw, 1280px
Responsive sizes attribute for the image.
widths array | default: array
Responsive width candidates used to generate image variants.
width number
Optional explicit image width in pixels.
height number
Optional explicit image height in pixels.
rounded boolean | default: false
Whether to apply rounded corners to the image.
aspectRatio enum | default: none
Set a fixed aspect ratio for the image.
Accepted values:
-
none -
square -
landscape -
portrait -
widescreen -
horizontal-strip
positionVertical enum | default: center
Vertical positioning of the image within the container (if aspect ratio is set).
Accepted values:
-
top -
center -
bottom
positionHorizontal enum | default: center
Horizontal positioning of the image within the container (if aspect ratio is set).
Accepted values:
-
left -
center -
right
priority boolean | default: false
Load the image with high priority (eager loading for above-the-fold images).
Examples #
Ratio #
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Castle" aspectRatio="square" source="/src/assets/images/component-docs/castle.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/castle.jpg
alt: Castle
aspectRatio: square
---
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Castle" aspectRatio="landscape" source="/src/assets/images/component-docs/castle.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/castle.jpg
alt: Castle
aspectRatio: landscape
---
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Castle" aspectRatio="portrait" source="/src/assets/images/component-docs/castle.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/castle.jpg
alt: Castle
aspectRatio: portrait
---
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Castle" aspectRatio="widescreen" source="/src/assets/images/component-docs/castle.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/castle.jpg
alt: Castle
aspectRatio: widescreen
---Position #
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Quiet Street" aspectRatio="square" positionHorizontal="left" positionVertical="top" source="/src/assets/images/component-docs/quiet-street.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/quiet-street.jpg
alt: Quiet Street
aspectRatio: square
positionVertical: top
positionHorizontal: left
---
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Quiet Street" aspectRatio="square" positionHorizontal="center" positionVertical="center" source="/src/assets/images/component-docs/quiet-street.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/quiet-street.jpg
alt: Quiet Street
aspectRatio: square
positionVertical: center
positionHorizontal: center
---
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Quiet Street" aspectRatio="square" positionHorizontal="right" positionVertical="bottom" source="/src/assets/images/component-docs/quiet-street.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/quiet-street.jpg
alt: Quiet Street
aspectRatio: square
positionVertical: bottom
positionHorizontal: right
---Rounded #
---
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Quiet Street" rounded source="/src/assets/images/component-docs/quiet-street.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/quiet-street.jpg
alt: Quiet Street
rounded: true
------
import Image from "@core-elements/image/Image.astro";
---
<Image alt="Quiet Street" source="/src/assets/images/component-docs/quiet-street.jpg" />---
blocks:
_component: building-blocks/core-elements/image
source: /src/assets/images/component-docs/quiet-street.jpg
alt: Quiet Street
---