Image
Image displays a photograph at its natural proportions or inside a chosen frame. It follows the available width, with the system’s small rounded corners.
A 16:9 frame crops the photograph while keeping its centre in view.
<ds-image src="/examples/images/forest.webp" alt="A path beneath tall trees in a sunlit forest" ratio="16 / 9" caption="A quiet path through the forest." style="max-width: 640px" loading="eager"></ds-image> Cover fills the square. Contain preserves the complete photograph.
<div style="display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:10px;max-width:640px"><ds-image src="/examples/images/lake.jpg" alt="A mountain reflected in a lake" ratio="1" fit="cover" caption="Cover" loading="eager"></ds-image><ds-image src="/examples/images/lake.jpg" alt="The full portrait photograph of a mountain and its reflection" ratio="1" fit="contain" caption="Contain" loading="eager"></ds-image></div> <ds-image src="/photos/forest.webp" alt="A sunlit path through tall trees" width="1200" height="800" ratio="16 / 9" caption="Along the forest path."></ds-image>srcandaltsupply the image and its text alternative. Usealt=""only for decorative images.widthandheightdescribe the source dimensions and reserve space before it loads.- Omit
ratioto keep natural proportions. Set it to1,4 / 3or16 / 9for a frame. fit="cover"fills that frame;fit="contain"shows the whole image.positionchooses the focal point, such as50% 25%.srcsetandsizeslet the browser select a responsive source.- Images load lazily by default. Use
loading="eager"for a prominent image at the top of the page. captionadds visible text underneath. It does not replacealt.
Copy image through Sync 1. React consumers can import Image from DS1/react/image after registering DS1/2-core/ds-image.
Behaviour
Section titled “Behaviour”The image takes the width of its column. While a picture loads, its frame shows the fill, so a reserved frame is not an empty hole. With a ratio the picture fills that frame; without one it keeps its own shape. An empty src requests nothing.
fit is cover unless it says contain, and loading is lazy unless it says eager. The browser decodes the picture without holding up the page. Words below it stand half a square under the picture, in the muted ink, on one square a line.
Accessibility
Section titled “Accessibility”alt goes straight to the native img. Write what the picture shows, or alt="" when it only decorates. A caption becomes a figcaption, and the picture stands in a figure with it.
| Attribute | Type | Default | What it does |
|---|---|---|---|
src | string | Empty | The picture’s address. |
alt | string | Empty | The text alternative. |
caption | string | Empty | Words shown underneath. |
srcset | string | Empty | Sources for the browser to choose from. |
sizes | string | Empty | The widths those sources are shown at. |
width | number | Unset | The source’s width, to reserve room. |
height | number | Unset | The source’s height, to reserve room. |
ratio | string | Empty | The frame’s shape, such as 16 / 9. |
fit | string | cover | cover or contain. |
position | string | center | The focal point. |
loading | string | lazy | lazy or eager. |
| Part | What it is |
|---|---|
media | The frame around the picture. |
image | The native img. |
caption | The figcaption. |
| Token | What it does |
|---|---|
--ds-image-background | The frame’s fill behind the picture, --ds-fill by default. |
--ds-image-end-radius | The corners at the end, for a container that cuts them. |
--ds-image-foot-radius | The corner at the foot and the start. |
It has no slots or events. Add hidden to hide it.
Example photographs
Section titled “Example photographs”Forest by Johannes Plenio on Unsplash, used under the Unsplash License. Mountain reflection by lil artsy on Pexels, used under the Pexels License. Example photos are stored with the documentation, outside the npm package.