The only Material UI image component to satisfy the Material Design guidelines for loading images.

Demo Playground ↗️

$3

> Illustrations and photographs may load and transition in three phases at staggered durations, rather than relying on opacity changes alone.
>
> Visualize the image fading in, like a print during the photo development process.
>
> \- Material guidelines

$3

``
pnpm add mui-image
`

or

`
npm i mui-image
`

or

`
bun add mui-image
`

or

`
yarn add mui-image
`

Using TypeScript? Also add @types/mui-image 🥳

$3

`
import { Image } from 'mui-image'

// then


`

$3

_Note: Profits not guaranteed and Material UI v5+ is a peer dependency. If you need to support legacy versions of Material UI, use material-ui-image instead. See the comparison chart below for more._

Usage Examples

You can use mui-image like a regular image.

`

`

Except... it will fade and animate in as the Material guidelines recommend. 🤯

Add a height and/or width to reserve space on the page for the image and avoid uncomforable content shifts as your picture loads. They both default to 100% of the parent you place them in and accept any valid CSS property. Numbers are converted to pixels.

`


`

Apply the showLoading prop to add a progress indicator to let your fans know something amazing is coming. You can use the default Material UI indicator or bring your own. 😎

`

} />
`

If you want the image to fail silently you can disable the errorIcon, or you can add your own to suit your brand.

`

} />
`

If you want to _disobey Google_ 😵 then you can customise the animation and speed via the duration and easing props to any valid CSS property. Duration is always milliseconds.

`


`

To add that extra bit of spice 🌶 you can do exactly what Google suggests and apply a small position shift to images as they appear. The direction, distance, and duration (in milliseconds) are up to you.

`



`

And of course, you can style mui-image like you would a regular image... but with the addition of the Material UI v5 sx prop and all the benefits it brings. 😏

`



`

If you want to get fancy 💃 you can also add inline styles and additional className's to the root wrapper div and loading/error icon wrapper div, or just target their default className's. This allows for complete customisation of every aspect of the component.

Like and subscribe below for more. ⏬

Props

| Name | Type | Default | Description |
| -------------------- | ---------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| alt | string | "" | image alt tag value |
| bgColor | string | "inherit" | the color the image transitions in from |
| className | string | "mui-image-img" | CSS class for the image |
| distance | string / number | 100 | any valid CSS length value (for the shift) |
| duration | number | 3000 | sets the CSS transition-duration in milliseconds |
| easing | string | cubic-bezier(0.7, 0, 0.6, 1) | sets the CSS transition-timing-function |
| errorIcon | boolean / node | true | display default error icon, or your own |
| fit | string | "contain" | any valid CSS object-fit value |
| height | number / string | "100%" | any valid CSS height value |
| iconWrapperClassName | string | "mui-image-iconWrapper" | CSS class for the icon wrapper div |
| iconWrapperStyle | object | | inline styles for the icon wrapper div |
| position | string | "relative" | any valid CSS position value |
| shift | boolean / string | false | either "left", "right", "top", "bottom", null, or false |
| shiftDuration | number | duration \* 0.3 | duration of shift in milliseconds |
| showLoading | boolean / node | false | display default loading spinner, or your own |
| _src_ \* | string | | image src tag... _required_ |
| style | object | | inline styles for the image |
| width | number / string | "100%" | any valid CSS width value |
| wrapperClassName | string | "mui-image-wrapper" | CSS class for the root wrapper div |
| wrapperStyle | object | | inline styles for the root wrapper div |

\* required prop

Any other props (eg. sx, onLoad) are passed directly to the native img element.

Material guidelines for loading images

> #### ✅ Fade-in
>
> Visualize the image fading in, like a print during the photo development process.

> #### ✅ Opacity, exposure, and saturation recommendations
>
> Images should begin loading with low contrast levels and desaturated color. Once image opacity reaches 100%, display the image with full-color saturation.

> #### ✅ Duration
>
> A longer duration is recommended for loading images, and a shorter duration is recommended for transitions.

> #### ✅ Animation
>
> Add a small position shift to loading images.

(Source)

Comparison with similar components

| Feature | mui-image | material-ui-image` |
| ----------------------------- | :------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------: |
| Size (minzipped) | !npm bundle size | !npm bundle size |
| Supports MUI v5 | ✅ | ❌ |
| Fade-in | ✅ | ✅ |
| Progressive level adjustments | ✅ | ❌ |
| Suggested duration | ✅ | ✅ |
| Optional shift animation | ✅ | ❌ |
| Supports legacy MUI versions | ❌ | ✅ |

License

© benmneb

ISC License

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.