# 📦 plugin-ideal-image

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

:::callout{intent="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

```bash 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')} />
```

:::callout{intent="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.
:::

:::callout{intent="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}`
:::

:::callout{intent="warning" title="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

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

Here's an example configuration:

```js title="docusaurus.config.js" {5-11}
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,
      },
    ],
  ],
};
```

## Related pages

- [Docusaurus plugins](./api-plugins-overview.md)
- [📦 plugin-content-docs](./api-plugins-plugin-content-docs.md)
- [📦 plugin-content-blog](./api-plugins-plugin-content-blog.md)
- [📦 plugin-content-pages](./api-plugins-plugin-content-pages.md)
- [📦 plugin-client-redirects](./api-plugins-plugin-client-redirects.md)
- [📦 plugin-debug](./api-plugins-plugin-debug.md)
- [📦 plugin-google-gtag](./api-plugins-plugin-google-gtag.md)
- [📦 plugin-rsdoctor](./api-plugins-plugin-rsdoctor.md)
- [📦 plugin-svgr](./api-plugins-plugin-svgr.md)
- [📦 plugin-google-tag-manager](./api-plugins-plugin-google-tag-manager.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.