Appearance

Image ​

Renders an image based on a provided url, or set of urls.

Basic usage ​

template
<Image src="https://picsum.photos/300" />

TIP

Try to always provide an alternative text via alt property. This allows screen readers to describe the image to visually impaired users.

Radius ​

You can specify the roundness of the image via the radius property, choosing from either none (default) or rounded.

template
<Image radius="none" src="https://picsum.photos/id/300/300" />
<Image radius="rounded" src="https://picsum.photos/id/300/300" />

Provider ​

You can specify where the image is served from, accepted values are static or cloudinary

Static ​

The src should either be relative to the defined staticPath, or an absolute URL. To use an absolute URL, the domain must be included in stashOptions.images.domains.

template
<Image src="https://picsum.photos/300" />

Cloudinary ​

With cloudinary as the provider, the src should be the absolute path to the original source image (eg. image served from the LeafLink CDN). The component will append the src onto the Cloudinary base url (inclusive of any transformations).

TIP

Inspect the image below in your dev tools so you can see the srcset property being populated.

template
<Image
  provider="cloudinary"
  src="https://d355b1w2e0hqb6.cloudfront.net/media/images/brands/2022/06/09/Apple_Tree_Nug_Q7RSrqm.png"
  sizes="100vw md:200px lg:400px"
/>

INFO

If no provider prop is specified, the component will try to retrieve this value from the stash options, falling back to static.

ts
app.use(Stash, {
  images: {
    provider: 'static',
  },
});

Srcset ​

Specifies a list of image files that the browser will use to select the most appropriate image based on the device's characteristics.

WARNING

When cloudinary is set as the provider, the srcset is ignored; the srcset gets auto-generated using the image size presets defined in the component. sizes will still need to be provided to define the responsive requirements.

template
<Image
  srcset="https://picsum.photos/id/237/400 400w,
          https://picsum.photos/id/237/1200 1200w"
  src="https://picsum.photos/id/237/300"
/>

Size presets ​

Image size presets are derived from the full container width (theme('width.container') minus margins: 1352) and are designed to satisfy @2x dpi requirements. The keys do not have a direct mapping to breakpoints.

  • xs → 160px
  • sm → 338px
  • md → 676px
  • lg → 1352px
  • xl → 2704px

Sizes ​

Informs the browser about the size of the image element as it will be displayed on the page across different media conditions. When omitted with srcset present, the default is 100vw.

Native ​

Works with native usage

template
<Image
  srcset="https://picsum.photos/id/237/200 200w,
          https://picsum.photos/id/237/1200 1200w"
  sizes="(min-width: 1000px) 1200px, 200px"
  src="https://picsum.photos/id/237/300"
/>

Custom API ​

The component supports a custom API for mapping image sizes to the design system breakpoints, and works across providers. It expects a string of breakpoint:width pairs, ordered mobile-first.

For example: 100vw md:200px lg:400px is the equivalent of writing (min-width: 961px) 400px, (min-width: 640px) 200px, 100vw. For defining mobile sizes (sm), omit the breakpoint. If you omit the mobile size, it will default to 100vw.

Supported breakpoints: md, lg

INFO

sizes does not support percentage values; applies to both the native and custom API.

template
<Image
  srcset="https://picsum.photos/id/237/200 200w,
          https://picsum.photos/id/237/1200 1200w"
  sizes="200px md:600px"
  src="https://picsum.photos/id/237/300"
/>

API ​

See the documentation below for a complete reference to all the props and classes available to the components mentioned here.