Image
Displays an image as a thumbnail or a figure, with a placeholder when there is none and a broken-image tile when it can't be loaded
<sa-stack>
<sa-item variant="ItemVariant.Outline" size="ItemSize.Small">
<sa-item-media>
<sa-image src="/cities/kyoto.jpg" alt="Kiyomizu-dera above red autumn foliage in Kyoto" size="ImageSize.Medium" />
</sa-item-media>
<sa-item-content>
<sa-item-title>Kyoto</sa-item-title>
<sa-item-description>Autumn temples, 6 nights</sa-item-description>
</sa-item-content>
</sa-item>
<sa-item variant="ItemVariant.Outline" size="ItemSize.Small">
<sa-item-media>
<sa-image src="/cities/lisbon.jpg" alt="Terracotta rooftops and historic churches in Lisbon" size="ImageSize.Medium" />
</sa-item-media>
<sa-item-content>
<sa-item-title>Lisbon</sa-item-title>
<sa-item-description>Tram 28 and the old town, 4 nights</sa-item-description>
</sa-item-content>
</sa-item>
</sa-stack>Usage
<sa-image> is a self-closing tag. Give it the image's URL in src and a description in alt.
<sa-image src="..." alt="..." />Images are thumbnails by default: a small square, the size of a list item's media or a table cell. Set variant to ImageVariant.Figure for a record's main image, such as on its details page.
Examples
Sizes
Set size to ImageSize.ExtraSmall, Small, Medium or Large. A thumbnail is 24, 32, 40 or 64 pixels tall, and Small is the default, which fits a table row.
<div class="flex items-end gap-4">
<sa-image src="/cities/cape-town.jpg" alt="Table Mountain above the Cape Town coast" size="ImageSize.ExtraSmall" />
<sa-image src="/cities/cape-town.jpg" alt="Table Mountain above the Cape Town coast" size="ImageSize.Small" />
<sa-image src="/cities/cape-town.jpg" alt="Table Mountain above the Cape Town coast" size="ImageSize.Medium" />
<sa-image src="/cities/cape-town.jpg" alt="Table Mountain above the Cape Town coast" size="ImageSize.Large" />
</div>Aspect ratio
Set aspect-ratio to ImageAspectRatio.Square, Landscape (4:3), Widescreen (16:9) or Portrait (3:4) to choose the box's shape; size sets its height. By default the image covers the box and its edges are cropped. Set fit to ImageFit.Contain to show the whole image inside the box on a quiet backdrop instead, as the last image here does. ImageAspectRatio.Original keeps the image's own shape.
<div class="flex flex-wrap items-end gap-4">
<sa-image src="/cities/chiang-mai.jpg" alt="Wat Chedi Luang in Chiang Mai" size="ImageSize.Large" />
<sa-image src="/cities/chiang-mai.jpg" alt="Wat Chedi Luang in Chiang Mai" size="ImageSize.Large" aspect-ratio="ImageAspectRatio.Landscape" />
<sa-image src="/cities/chiang-mai.jpg" alt="Wat Chedi Luang in Chiang Mai" size="ImageSize.Large" aspect-ratio="ImageAspectRatio.Widescreen" />
<sa-image src="/cities/chiang-mai.jpg" alt="Wat Chedi Luang in Chiang Mai" size="ImageSize.Large" aspect-ratio="ImageAspectRatio.Portrait" />
<sa-image src="/cities/chiang-mai.jpg" alt="Wat Chedi Luang in Chiang Mai" size="ImageSize.Large" aspect-ratio="ImageAspectRatio.Widescreen" fit="ImageFit.Contain" />
</div>Figure
A figure keeps the image's own shape by default and grows to the width of its container, up to a maximum height that size sets: 8, 10, 15 or 20rem, with Medium as the default. Corners follow the theme's radius for boxes. A figure without an image reads "No image", so it suits a details page where every record has the same layout.
<sa-details>
<sa-display-field label="Destination">Lisbon, Portugal</sa-display-field>
<sa-display-field label="Cover photo">
<sa-image src="/cities/lisbon.jpg" alt="Terracotta rooftops and historic churches in Lisbon" variant="ImageVariant.Figure" />
</sa-display-field>
</sa-details>Interaction
An image with a src is a button that opens the image larger in a dialog, which closes with its close button, Escape or a click outside. The first image of a page that can open it writes the dialog's template, so a page with many images still has one dialog. Set interaction to ImageInteraction.Preview to show the larger image beside the thumbnail on hover instead, or to ImageInteraction.None for an image that does neither.
<div class="flex items-center gap-4">
<sa-image src="/cities/kyoto.jpg" alt="Kiyomizu-dera above red autumn foliage in Kyoto" size="ImageSize.Large" />
<sa-image src="/cities/lisbon.jpg" alt="Terracotta rooftops and historic churches in Lisbon" size="ImageSize.Large" interaction="ImageInteraction.Preview" />
<sa-image src="/cities/cape-town.jpg" alt="Table Mountain above the Cape Town coast" size="ImageSize.Large" interaction="ImageInteraction.None" />
</div>The button is named by alt, so always describe the image; without alt it is named "View image".
Empty and broken images
Without a src the image shows a placeholder, and an image that fails to load shows a broken-image tile in its place, which the script sets from the image's error event. A figure adds a short message to either. The tile replaces the button, so a broken image cannot open an empty dialog.
<div class="flex flex-wrap items-start gap-6">
<sa-image size="ImageSize.Large" />
<sa-image src="/cities/valparaiso.jpg" alt="Colourful houses on the hills of Valparaíso" size="ImageSize.Large" />
<sa-image variant="ImageVariant.Figure" size="ImageSize.ExtraSmall" aspect-ratio="ImageAspectRatio.Landscape" />
<sa-image src="/cities/valparaiso.jpg" alt="Colourful houses on the hills of Valparaíso" variant="ImageVariant.Figure" size="ImageSize.ExtraSmall" aspect-ratio="ImageAspectRatio.Landscape" />
</div>API Reference
<sa-image>
Renders a <button> element for an image that opens a dialog, and a <span> element otherwise, holding an <img> and the placeholder and broken-image fallbacks, forwarding any global attributes.
Prop
Type