react-responsive-picture
A future-proof responsive image component that supports latest <picture>
specification. Uses picturefill for backward compatibility from IE9+.
Installation
npm install react-responsive-picture
or yarn add react-responsive-picture
Playground
You can also run the examples by cloning the repo and running yarn start
.
Usage
import Picture from 'react-responsive-picture'; { return <Picture = /> ;}
Props
Prop | Type | Default | Definition |
---|---|---|---|
sources | array | The array of source objects. Check Sources section for more information. | |
src | string | (transparent pixel) | Source for standalone/fallback image. To prevent issues in some browsers, by default src is set to a 1x1 transparent pixel data image. |
sizes | string | Sizes attribute to be used with src for determing best image for user's viewport. |
|
alt | string | Alternative text for image | |
className | string | Any additional CSS classes you might want to use to style the image |
Examples
Simple image
Normal <img>
like behaviour. The same image is displayed on every device/viewport.
<Picture ="path-to-image.jpg" />
will render:
Image with different resolutions
Different images for specific devices (usually retina).
<Picture ="path-to-image@2x.png 2x, path-to-image.png 1x" />
will render:
Image with sizes
When you want to let the browser determine the best image for user's current viewport. More information about size
attribute on this great blog post.
<Picture ="large.jpg 1024w, medium.jpg 640w, small.jpg 320w" ="(min-width: 36em) 33.3vw, 100vw"/>
will render:
Image with art direction
When you want to explicitly control which image is displayed at specific viewport sizes.
<Picture = />
will render:
The sources
prop is where you can determine the behaviour of the <Picture>
component and which images will show for the specific screens.
For each source you can send an object containing srcSet
, media
and type
although the last two are optional.
Styling
You can use your favourite styling library and style the Picture
component using the className
prop.
import css from "emotion"; <Picture = ="path-to-image@2x.png 2x, path-to-image.png 1x" />
Fullsize images
There's also a <FullsizePicture>
component that you can use to display full-size images using the same benefits of <Picture>
for art direction.
<div => <FullsizePicture = /></div>
It will automatically fill the parent element maintaining the original image ratio. Please note that the parent element needs to have a defined height as you would expect for any background image as well.
Props
FullsizePicture
accepts the same props as Picture
plus a few more for styling and positioning.
Prop | Type | Default | Definition |
---|---|---|---|
sources | array | The array of source objects. Check Sources section for more information. | |
src | string | (transparent pixel) | Source for standalone/fallback image. To prevent issues in some browsers, by default src is set to a 1x1 transparent pixel data image. |
sizes | string | Sizes attribute to be used with src for determing best image for user's viewport. |
|
alt | string | Alternative text for image | |
className | string | Any additional CSS classes you might want to use to style the image | |
wrapperClassName | string | Any additional CSS classes you might want to use to style the wrapper of the Picture component |
|
cover | "both" | "width" | "height" | "both" | Decides the fullsize behaviour of the Picture component. By default it covers the entire parent, but can be changed to cover just the height or width instead. |
center | boolean | true | Helper prop to horizontally and vertically center the image. |
Use as background image
If you want to use FullsizePicture
as a background image for other components, you can pass them as children too.
<section => <FullsizePicture = > <Heading1>This is the section title</Heading1> </FullsizePicture></section>
Contributing
Please follow our contributing guidelines.