picture

Provides instructions for browsers to use alternative image versions in various scenarios

import { CdrPicture } from '@rei/cedar'
Uses: CdrImg

Live demo

Purpose

The CdrPicture provides a convenient data interface for setting up complex art direction for the HTML <picture> element.

Best practices

Picture vs. image

Use CdrPicture for art direction:

Opt for CdrPicture when you need different images (or different crops of an image) at different breakpoints. This is particularly useful for art direction, where the focal point of an image might change based on the screen size.

Use srcset with CdrImg for scaling:

When you only need to scale the same image for different resolutions and sizes, using srcset with the CdrImg component is enough. This approach is ideal for straightforward responsive images where the aspect ratio and composition remain constant across devices.

Usage

When to use

  • Needing different versions of the image for different screen sizes
  • Wanting fine-grained control over which images to display at specific breakpoints
  • Providing an alt attribute for accessibility (note that the same alt attribute will be used for all images)

When not to use

  • Displaying images that don't require responsiveness
  • Creating sets of images where the only difference is image resolution. The srcset attribute in CdrImg is a more appropriate choice ::

Implementation

The CdrPicture component is designed for responsive image handling. Define different image sources for various breakpoints using the sources prop.

<script setup lang="ts">
import { CdrPicture, type pictureSourceObject } from '@rei/cedar';

// CdrPicture expects an Object of pictureSourceObjects passed to the sources property
defineProps<{
  sources: pictureSourceObject;
}>();

const sourceObj = {
  mobile: {
    media: '(max-width: 768px)',
    srcset: 'nature-mobile-300x300.jpg 300w nature-mobile-500x500.jpg 500w',
    sizes: '100vw',
  },
  desktop: {
    media: '(min-width: 769px)',
    srcset: 'nature-desktop-704x396.jpg 704w nature-desktop-1280x720.jpg 1280w',
    width: '100vw',
  },
};
</script>

<template>
  <cdr-picture
    src="nature.jpg"
    alt="A scenic nature view"
    :sources="sourceObj"
  />
</template>

The CdrPicture component will then populate the sources prop:

<picture>
  <!-- Sources for different breakpoints -->
  <source
    media="(max-width: 768px)"
    srcset="nature-mobile-300x300.jpg 300w nature-mobile-500x500.jpg 500w"
    sizes="100vw"
  />
  <source
    media="(min-width: 769px)"
    srcset="nature-desktop-704x396.jpg 704w nature-desktop-1280x720.jpg 1280w"
    sizes="100vw"
  />

  <!-- Default image -->
  <img
    src="nature.jpg"
    alt="A scenic nature view"
  />
</picture>

TypeScript

When using CdrPicture in a TypeScript application, we recommend importing the pictureSourceObject interface from the library so you can correctly define the component props.

CdrPicture expects an object of sources with a specific schema, so using this interface will prevent you from needing to define your own. Using a helper extension In VS Code, like Volar, will give you helpful hints when importing this interface as well.

ParentComponent.vue

<script setup lang="ts">
import { CdrPicture, type pictureSourceObject } from '@rei/cedar';

// CdrPicture expects an Object of pictureSourceObjects passed to the sources property
defineProps<{
  sources: pictureSourceObject;
}>();
</script>

<template>
  <div>
    <h2>picture</h2>
    <cdr-picture
      src="/src/dev/static/test-image.png"
      loading="eager"
      :sources="sources"
    />
  </div>
</template>

API

CdrPicture

Props

NameTypeDefault
alt