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 wide photograph

A 16:9 frame crops the photograph while keeping its centre in view.

Crop or show the whole image

Cover fills the square. Contain preserves the complete photograph.

<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>
  • src and alt supply the image and its text alternative. Use alt="" only for decorative images.
  • width and height describe the source dimensions and reserve space before it loads.
  • Omit ratio to keep natural proportions. Set it to 1, 4 / 3 or 16 / 9 for a frame.
  • fit="cover" fills that frame; fit="contain" shows the whole image. position chooses the focal point, such as 50% 25%.
  • srcset and sizes let the browser select a responsive source.
  • Images load lazily by default. Use loading="eager" for a prominent image at the top of the page.
  • caption adds visible text underneath. It does not replace alt.

Copy image through Sync 1. React consumers can import Image from DS1/react/image after registering DS1/2-core/ds-image.

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.

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.

AttributeTypeDefaultWhat it does
srcstringEmptyThe picture’s address.
altstringEmptyThe text alternative.
captionstringEmptyWords shown underneath.
srcsetstringEmptySources for the browser to choose from.
sizesstringEmptyThe widths those sources are shown at.
widthnumberUnsetThe source’s width, to reserve room.
heightnumberUnsetThe source’s height, to reserve room.
ratiostringEmptyThe frame’s shape, such as 16 / 9.
fitstringcovercover or contain.
positionstringcenterThe focal point.
loadingstringlazylazy or eager.
PartWhat it is
mediaThe frame around the picture.
imageThe native img.
captionThe figcaption.
TokenWhat it does
--ds-image-backgroundThe frame’s fill behind the picture, --ds-fill by default.
--ds-image-end-radiusThe corners at the end, for a container that cuts them.
--ds-image-foot-radiusThe corner at the foot and the start.

It has no slots or events. Add hidden to hide it.

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.