📦 plugin-ideal-image

Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).

Installation

npm2yarn

npm install --save @docusaurus/plugin-ideal-image

Usage

This plugin supports the PNG and JPG formats only.

JSX

import Image from '@theme/IdealImage';
import thumbnail from './path/to/img.png';

// your React code
<Image img={thumbnail} />

// or
<Image img={require('./path/to/img.png')} />

When plugin-ideal-image is installed, importing a supported image file no longer returns a plain URL string. Instead, it returns an object with the shape: { preSrc: string, src: { src: string, width: number, height: number } }.

If you need to use the image in a standard <img> tag, access it like this:

JSX

<img
  src={image.src.src}
  width={image.src.width}
  height={image.src.height}
  alt="description"
/>

To avoid dealing with this object shape directly, it is recommended to use the <Image> component provided by this plugin instead.

For pnpm users

Starting with pnpm 10, running pnpm install won't run dependency install scripts by default. You'll need additional pnpm configuration (issue) for our sharp image resizing dependency to install correctly, such as:

package.json

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

Configuration

Accepted fields:

mdx-code-block

<APITable>

Option	Type	Default	Description
`name`	`string`	`ideal-img/[name].[hash:hex:7].[width].[ext]`	Filename template for output files.
`sizes`	`number[]`	original size	Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).
`size`	`number`	original size	Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up)
`min`	`number`		As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you.
`max`	`number`		See `min` above
`steps`	`number`	`4`	Configure the number of images generated between `min` and `max` (inclusive)
`quality`	`number`	`85`	JPEG compression quality
`disableInDev`	`boolean`	`true`	You can test ideal image behavior in dev mode by setting this to `false`. Tip: use network throttling in your browser to simulate slow networks.

mdx-code-block

</APITable>

Example configuration

Here's an example configuration:

docusaurus.config.js

export default {  plugins: [    [      '@docusaurus/plugin-ideal-image',      {        quality: 70,        max: 1030, // max resized image's size.        min: 640, // min resized image's size. if original is lower, use that size.        steps: 2, // the max number of images generated between min and max (inclusive)        disableInDev: false,      },    ],  ],};