Docusaurus Native Ideal Image Plugin

A Docusaurus plugin for pre-processing images to multiple formats, sizes and low quality image placeholders

This replaces the official @docusaurus/plugin-ideal-image through modern browser native srcset and lazy loading

Why

The official @docusaurus/plugin-ideal-image has some limitations and bugs which this package was made to solve:

• Image flashing when navigating back and forward
• Buggy low bandwidth detection that replaces the image with a 'Click to load' text instead of just loading it.
• Doesn't support newer image formats that has better compression ratios like WebP and AVIF

Apart from these, using browser native features is more performant, and resulting in smaller bundle sizes

Usage

First install

npm install docusaurus-plugin-native-ideal-image

And add the configuration to docusaurus.config.js/docusaurus.config.ts

const config = {
    ...
    plugins: ['native-ideal-image'],
}

Then you can use it in your project like this

import image from 'ideal-img!../images/some-image.jpeg'

<NativeIdealImage img={image} />

// or with require
<NativeIdealImage img={require('ideal-img!../images/some-image.jpeg')} />

To use it for markdown images by default, add this to the configuration

import { nativeIdealImageRemarkPlugin } from 'docusaurus-plugin-native-ideal-image'

const config = {
    presets: [
        [
            'classic',
            {
                // The same for docs and blog
                pages: {
                    remarkPlugins: [nativeIdealImageRemarkPlugin],
                },
                ...
            },
        ],
    ],
}

By default, this will transform the image into a jpeg source and a webp source and also a webp format low quality placeholder, and end up like this

<picture
	class="native-ideal-img"
	style="--lqip: url(data:image/webp;base64,UklGRj4AAABXRUJQVlA4IDIAAADQAQCdASoQAAwABUB8JZQAAudcoVPyIAD+uVyF4iJZsGTWpdieB7utExa6oMeh0PusAA==);"
>
	<source srcset="assets/native-ideal-image/some-image-b0600-2160.webp" type="image/webp" />
	<img
		loading="lazy"
		src="assets/native-ideal-image/some-image-6ee75-2160.jpeg"
		width="2160"
		height="1620"
	/>
</picture>

You can use query strings to change the output, currently you can do

• w: changes the output sizes
• formats: changes the formats used
• presets: use a preset set in the config

Example: import image from 'ideal-img!../images/some-image.jpeg?w=800,1200&formats=avif,webp'

You can learn more in the example directory or see some live examples in https://legend-master.github.io/docusaurus-plugin-native-ideal-image

TypeScript

To use with TypeScript, put "docusaurus-plugin-native-ideal-image/types" in compilerOptions > types in your tsconfig.json or put /// <reference type="docusaurus-plugin-native-ideal-image/types" in a .d.ts file to get @theme/NativeIdealImage and ideal-img!* type