Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cyrilwanner/react-optimized-image
Easy to use React components for optimized-images-loader / next-optimized-images.
https://github.com/cyrilwanner/react-optimized-image
image optimization react
Last synced: 17 days ago
JSON representation
Easy to use React components for optimized-images-loader / next-optimized-images.
- Host: GitHub
- URL: https://github.com/cyrilwanner/react-optimized-image
- Owner: cyrilwanner
- License: mit
- Created: 2020-06-11T20:24:16.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-12-11T15:32:09.000Z (about 2 years ago)
- Last Synced: 2025-01-03T07:33:37.154Z (19 days ago)
- Topics: image, optimization, react
- Language: TypeScript
- Homepage:
- Size: 412 KB
- Stars: 62
- Watchers: 4
- Forks: 8
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-optimized-image [](https://www.npmjs.com/package/react-optimized-image) [](https://github.com/cyrilwanner/react-optimized-image/blob/master/LICENSE) [](https://www.npmjs.com/package/react-optimized-image)
Features:
- **Optimize** images using WebAssembly (runs in every environment)
- **React components** for different use-cases (responsive images, WebP conversion, lazy loading placeholders, image manipulation, ...)
- **Build cache for images** for faster builds
- **Convert to WebP** automatically during a webpack build
- **Inline** small images automatically
- ...
## Table of contents
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Image components](#image-components)
- [Global image config](#global-image-config)
- [License](#license)
## Requirements
This image components requires [optimized-images-loader](https://github.com/cyrilwanner/optimized-images-loader) to already be installed and configured.
If you are using Next.js, you can use the [next-optimized-images](https://github.com/cyrilwanner/next-optimized-images) plugin instead for easier configuration.
## Installation
```
npm install react-optimized-image
```
Add the `react-optimized-image/plugin` babel plugin to your `.babelrc` file.
If you don't yet have a `.babelrc` file, create one with the following content:
```json
{
"plugins": ["react-optimized-image/plugin"]
}
```
## Usage
You can now import or require your images directly in your react components:
```javascript
import React from 'react';
import Img from 'react-optimized-image';
import Header from './images/header.jpg';
export default () => (
{/* with import statement ..*/}
{/* ..or an inline require */}
})
);
/**
* Results in:
*
*
* 
* 
*
*/
```
### Image components
For easier use and full typescript support, this plugin provides some image components.
* [`Img`](#img)
* [`Svg`](#svg)
#### Img
The `Img` component can be used to include a normal image. Additionally, it can create a WebP fallback and provide different sizes for different viewports.
##### Usage
```javascript
import Img from 'react-optimized-image';
import MyImage from './images/my-image.jpg';
export default () => (
<>
Normal optimized image
Image will be resized to 400px width
A WebP image will be served in two sizes: 400px and 800px
As a fallback, a jpeg image will be provided (also in both sizes)
>
);
/**
* Results in:
*
*
Normal optimized image
*
*
* Image will be resized to 400px width
* 
*
* A WebP image will be served in two sizes: 400px and 800px
* As a fallback, a jpeg image will be provided (also in both sizes)
*
*
*
*
*
* 
*
*/
```
##### Properties
| Prop | Required | Type | Description |
| :--- | :------: | :--: | :---------- |
| src | **yes** | `string` | Source image. |
| webp | | `boolean` | If true, the image will get converted to WebP. For browsers which don't support WebP, an image in the original format will be served. |
| sizes | | `number[]` | Resize the image to the given width. If only one size is present, an `![]()
` tag will get generated, otherwise a `` tag for multiple sizes. |
| densities | | `number[]` | **Default:** `[1]`
Specifies the supported pixel densities. For example, to generate images for retina displays, set this value to `[1, 2]`. |
| breakpoints | | `number[]` | Specifies the breakpoints used to decide which image size to use (when the `size` property is present). If no breakpoints are specified, they will automatically be set to match the image sizes which is good for full-width images but result in too big images in other cases.
The breakpoints should have the same order as the image sizes.
Example for this query: ```sizes={[400, 800, 1200]} breakpoints={[600, 1000]}```
For widths 0px-600px the 400px image will be used, for 601px-1000px the 800px image will be used and for everything larger than 1001px, the 1200px image will be used. |
| inline | | `boolean` | If true, the image will get forced to an inline data-uri (e.g. `data:image/png;base64,...`). |
| url | | `boolean` | If true, the image will get forced to be referenced with an url, even if it is a small image and would get inlined by default. |
| original | | `boolean` | If true, the image will not get optimized (but still resized if the `sizes` property is present). |
| type | | `string` | So you don't have to repeat yourself by setting the same sizes or other properties on many images, specify the image type which equals to one in your [global image config](#global-image-config). |
| *anything else* | | `ImgHTMLAttributes` | All other properties will be directly passed to the `![]()
` tag. So it would for example be possible to use native lazy-loading with `loading="lazy"`. |
#### Svg
The `Svg` includes an svg file directly into the HTML so it can be styled by CSS. If you don't want to include them directly in the HTML, you can also use svg images together with the [`Img`](#img) component which will reference it by the URL.
##### Usage
```javascript
import { Svg } from 'react-optimized-image';
import Icon from './icons/my-icon.svg';
export default () => (
<>
SVG will be directly included in the HTML
>
);
/**
* Results in:
*
* ...
*/
```
##### Properties
| Prop | Required | Type | Description |
| :--- | :------: | :--: | :---------- |
| src | **yes** | `string` | Source image. |
| className | | `string` | Class to apply to the `` tag. |
## Global image config
The `images.config.js` file contains default image optimization options and is located in the **root** of your project.
Available options:
| Option | Type | Description |
| :--- | :------: | :---------- |
| default | `ImgProps` | Properties specified within the `default` key will get applied to **all** usages of the [`Img`](#img) components.
All properties of the [`Img`](#img) component can be set. For example, to convert **all** your images to WebP, set `{ webp: true }`. |
| types | `Record` | Instead of specifying options for **all** images with the `default` key, you can create as many image `types` as you want. Those can also contain all properties of the [`Img`](#img) component. The options specified in the `default` key will also get applied here if they are not overwritten. |
#### Example
```javascript
// images.config.js
module.exports = {
default: {
webp: true,
},
types: {
thumbnail: {
sizes: [200, 400],
breakpoints: [800],
webp: false,
},
},
};
```
This will convert **all images** to WebP. The images with the `thumbnail` type will be generated in two sizes (200, 400) but not converted to WebP. If `webp: false` would not be present, it would get inherited from the `default` key.
```javascript
import React from 'react';
import Img from 'react-optimized-image';
import MyImage from './images/my-image.jpg';
export default () => (
{/* This will get converted into a WebP image (while still providing a fallback image). */}
{/* This will be provided in to sizes (200, 400) but not get converted to WebP. */}
);
```
## License
Licensed under the [MIT](https://github.com/cyrilwanner/react-optimized-image/blob/master/LICENSE) license.
© Copyright Cyril Wanner