Uploadcare-picture NPM

Uploadcare Picture

This is an Uploadcare responsive <picture> component. It provides more control over image behavior: you can adjust image sizes to different media queries, control output formats, etc.

You also get:

Less code
All images served via Uploadcare CDN
One uploaded image and all of its versions generated on-the-fly via UC Image Processing

Install

You can get the component via npm:

npm install uploadcare-picture

You would not need an Uploadcare account for testing purposes: just use UUIDs provided in this readme. However, implementing the component requires you to have an Uploadcare account; you can get one here.

Usage

The function can be used directly or through one of the adapters.

import getPictureObject from 'uploadcare-picture'

const uuid = '18d1c520-c52d-4c34-82a0-7e07dcbcf105'
const options = {
  sizes: {
    '(max-width: 1024px)': '768px',
    'default': '1024px'
  },
  formats: ['jpg', 'webp'],
  name: 'example'
}
const picture = getPictureObject(uuid, options)

The function provides an object in the output, like this:

{
  sources: [
    {
      srcset: `https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/768x/-/format/webp/example.webp 1x, https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/1536x/-/format/webp/example.webp 2x`,
      type: 'image/webp',
      media: '(max-width: 1024px)',
      sizes: '768px',
    },
    {
      srcset: `https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/1024x/-/format/webp/example.webp 1x, https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/2048x/-/format/webp/example.webp 2x`,
      type: 'image/webp',
      sizes: '1024px',
    },
    {
      srcset: `https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/768x/-/format/jpg/example.jpg 1x, https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/1536x/-/format/jpg/example.jpg 2x`,
      type: 'image/jpg',
      media: '(max-width: 1024px)',
      sizes: '768px',
    },
    {
      srcset: `https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/1024x/-/format/jpg/example.jpg 1x, https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/2048x/-/format/jpg/example.jpg 2x`,
      type: 'image/jpg',
      sizes: '1024px',
    },
  ],
  image: {
    alt: 'example',
    src: `https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/1024x/-/format/auto/example`,
    srcset: `https://ucarecdn.com/18d1c520-c52d-4c34-82a0-7e07dcbcf105/-/resize/2048x/-/format/auto/example 2x`,
    sizes: '1024px',
  },
}

You can further transpile such objects to <picture> via any library or framework you like.

Options

width `string|number`

Required, if not set sizes.default.

Sets the width of an <img /> element.

sizes `object`

Required, if not set width.

Keys in the object are media queries while sizes define your picture dimensions for them.

formats `array<string>`

Optional, default values is ['auto'].

An array holding the allowed formats for your picture sources.

pixel_density `array<number|string>|number|string`

Optional, default value is [1, 2].

An array of pixel density value(-s) for resizing your picture sources.

name `string`

Optional.

An RFC3986-compliant filename.

Adapters

JSX

import UploadcarePicture from 'uploadcare-picture/adapters/jsx'

const Picture = () =>
  <UploadcarePicture
    uuid='18d1c520-c52d-4c34-82a0-7e07dcbcf105'
    formats={['webp', 'jpg']}
    sizes={{
      '(max-width: 1024px)': '768px',
      'default': 1024,
    }}
    name='example' />

Nunjucks

import {configure} from 'nunjucks'
import UploadcarePicture from 'uploadcare-picture/adapters/nunjucks'

const nunjucks = configure('templates', {autoescape: false})

nunjucks.addExtension('UploadcarePicture', new UploadcarePicture())

const template = `{% uploadcarePicture
  uuid='18d1c520-c52d-4c34-82a0-7e07dcbcf105',
  formats=['webp', 'jpg'],
  sizes={
    '(max-width: 1024px)': 768,
    'default': 1024
  },
  name='example'
%}`

const picture = nunjucks.renderString(template)