website/docs/api/plugins/plugin-ideal-image.mdx - main - githubmirror/docusaurus

website/docs/api/plugins/plugin-ideal-image.mdx
125 строк4 KB
Ifeanyi Chima
docs: document that plugin-ideal-image changes imported image types (#12130)
12 июн 2026, 14:10
12 июн 2026, 14:10b7963e3
---
sidebar_position: 8
slug: /api/plugins/@docusaurus/plugin-ideal-image
---

# 📦 plugin-ideal-image

import APITable from '@site/src/components/APITable';

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

:::info

By default, the plugin is **inactive in development** so you could always view full-scale images. If you want to debug the ideal image behavior, you could set the [`disableInDev`](#disableInDev) option to `false`.

:::

## Installation {/* #installation */}

```bash npm2yarn
npm install --save @docusaurus/plugin-ideal-image
```

## Usage {/* #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')} />
```

:::note

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.

:::

:::warning

This plugin registers a [Webpack loader](https://webpack.js.org/loaders/) that changes the type of imported/require images:

- Before: `string`
- After: `{preSrc: string, src: import("@theme/IdealImage").SrcImage}`

:::

:::warning For pnpm users

Starting with [pnpm 10](https://github.com/pnpm/pnpm/releases/tag/v10.0.0), running `pnpm install` won't run dependency install scripts by default. You'll need additional pnpm configuration ([issue](https://github.com/lovell/sharp/issues/4343)) for our `sharp` image resizing dependency to install correctly, such as:

```json title="package.json"
{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}
```

:::

## Configuration {/* #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](https://www.browserstack.com/guide/how-to-perform-network-throttling-in-chrome) in your browser to simulate slow networks. |

```mdx-code-block
</APITable>
```

### Example configuration {/* #ex-config */}

Here's an example configuration:

```js title="docusaurus.config.js"
export default {
  plugins: [
    [
      '@docusaurus/plugin-ideal-image',
      // highlight-start
      {
        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,
      },
      // highlight-end
    ],
  ],
};
```