---
productId: material-ui
title: Image List React component
components: ImageList, ImageListItem, ImageListItemBar
materialDesign: https://m2.material.io/components/image-lists
githubLabel: 'scope: image list'
githubSource: packages/mui-material/src/ImageList
---
# Image List
The Image List displays a collection of images in an organized grid.
Image lists represent a collection of items in a repeated pattern. They help improve the visual comprehension of the content they hold.
## Standard image list
Standard image lists are best for items of equal importance. They have a uniform container size, ratio, and spacing.
```tsx
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
export default function StandardImageList() {
return (
{itemData.map((item) => (
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1551963831-b3b1ca40c98e',
title: 'Breakfast',
},
{
img: 'https://images.unsplash.com/photo-1551782450-a2132b4ba21d',
title: 'Burger',
},
{
img: 'https://images.unsplash.com/photo-1522770179533-24471fcdba45',
title: 'Camera',
},
{
img: 'https://images.unsplash.com/photo-1444418776041-9c7e33cc5a9c',
title: 'Coffee',
},
{
img: 'https://images.unsplash.com/photo-1533827432537-70133748f5c8',
title: 'Hats',
},
{
img: 'https://images.unsplash.com/photo-1558642452-9d2a7deb7f62',
title: 'Honey',
},
{
img: 'https://images.unsplash.com/photo-1516802273409-68526ee1bdd6',
title: 'Basketball',
},
{
img: 'https://images.unsplash.com/photo-1518756131217-31eb79b20e8f',
title: 'Fern',
},
{
img: 'https://images.unsplash.com/photo-1597645587822-e99fa5d45d25',
title: 'Mushrooms',
},
{
img: 'https://images.unsplash.com/photo-1567306301408-9b74779a11af',
title: 'Tomato basil',
},
{
img: 'https://images.unsplash.com/photo-1471357674240-e1a485acb3e1',
title: 'Sea star',
},
{
img: 'https://images.unsplash.com/photo-1589118949245-7d38baf380d6',
title: 'Bike',
},
];
```
## Quilted image list
Quilted image lists emphasize certain items over others in a collection. They create hierarchy using varied container sizes and ratios.
```tsx
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
function srcset(image: string, size: number, rows = 1, cols = 1) {
return {
src: `${image}?w=${size * cols}&h=${size * rows}&fit=crop&auto=format`,
srcSet: `${image}?w=${size * cols}&h=${
size * rows
}&fit=crop&auto=format&dpr=2 2x`,
};
}
export default function QuiltedImageList() {
return (
{itemData.map((item) => (
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1551963831-b3b1ca40c98e',
title: 'Breakfast',
rows: 2,
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1551782450-a2132b4ba21d',
title: 'Burger',
},
{
img: 'https://images.unsplash.com/photo-1522770179533-24471fcdba45',
title: 'Camera',
},
{
img: 'https://images.unsplash.com/photo-1444418776041-9c7e33cc5a9c',
title: 'Coffee',
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1533827432537-70133748f5c8',
title: 'Hats',
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1558642452-9d2a7deb7f62',
title: 'Honey',
author: '@arwinneil',
rows: 2,
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1516802273409-68526ee1bdd6',
title: 'Basketball',
},
{
img: 'https://images.unsplash.com/photo-1518756131217-31eb79b20e8f',
title: 'Fern',
},
{
img: 'https://images.unsplash.com/photo-1597645587822-e99fa5d45d25',
title: 'Mushrooms',
rows: 2,
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1567306301408-9b74779a11af',
title: 'Tomato basil',
},
{
img: 'https://images.unsplash.com/photo-1471357674240-e1a485acb3e1',
title: 'Sea star',
},
{
img: 'https://images.unsplash.com/photo-1589118949245-7d38baf380d6',
title: 'Bike',
cols: 2,
},
];
```
## Woven image list
Woven image lists use alternating container ratios to create a rhythmic layout. A woven image list is best for browsing peer content.
```tsx
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
export default function WovenImageList() {
return (
{itemData.map((item) => (
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1549388604-817d15aa0110',
title: 'Bed',
},
{
img: 'https://images.unsplash.com/photo-1563298723-dcfebaa392e3',
title: 'Kitchen',
},
{
img: 'https://images.unsplash.com/photo-1523413651479-597eb2da0ad6',
title: 'Sink',
},
{
img: 'https://images.unsplash.com/photo-1525097487452-6278ff080c31',
title: 'Books',
},
{
img: 'https://images.unsplash.com/photo-1574180045827-681f8a1a9622',
title: 'Chairs',
},
{
img: 'https://images.unsplash.com/photo-1597262975002-c5c3b14bbd62',
title: 'Candle',
},
{
img: 'https://images.unsplash.com/photo-1530731141654-5993c3016c77',
title: 'Laptop',
},
{
img: 'https://images.unsplash.com/photo-1481277542470-605612bd2d61',
title: 'Doors',
},
{
img: 'https://images.unsplash.com/photo-1517487881594-2787fef5ebf7',
title: 'Coffee',
},
{
img: 'https://images.unsplash.com/photo-1516455207990-7a41ce80f7ee',
title: 'Storage',
},
{
img: 'https://images.unsplash.com/photo-1519710164239-da123dc03ef4',
title: 'Coffee table',
},
{
img: 'https://images.unsplash.com/photo-1588436706487-9d55d73a39e3',
title: 'Blinds',
},
];
```
## Masonry image list
Masonry image lists use dynamically sized container heights that reflect the aspect ratio of each image. This image list is best used for browsing uncropped peer content.
```tsx
import Box from '@mui/material/Box';
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
export default function MasonryImageList() {
return (
{itemData.map((item) => (
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1549388604-817d15aa0110',
title: 'Bed',
},
{
img: 'https://images.unsplash.com/photo-1525097487452-6278ff080c31',
title: 'Books',
},
{
img: 'https://images.unsplash.com/photo-1523413651479-597eb2da0ad6',
title: 'Sink',
},
{
img: 'https://images.unsplash.com/photo-1563298723-dcfebaa392e3',
title: 'Kitchen',
},
{
img: 'https://images.unsplash.com/photo-1588436706487-9d55d73a39e3',
title: 'Blinds',
},
{
img: 'https://images.unsplash.com/photo-1574180045827-681f8a1a9622',
title: 'Chairs',
},
{
img: 'https://images.unsplash.com/photo-1530731141654-5993c3016c77',
title: 'Laptop',
},
{
img: 'https://images.unsplash.com/photo-1481277542470-605612bd2d61',
title: 'Doors',
},
{
img: 'https://images.unsplash.com/photo-1517487881594-2787fef5ebf7',
title: 'Coffee',
},
{
img: 'https://images.unsplash.com/photo-1516455207990-7a41ce80f7ee',
title: 'Storage',
},
{
img: 'https://images.unsplash.com/photo-1597262975002-c5c3b14bbd62',
title: 'Candle',
},
{
img: 'https://images.unsplash.com/photo-1519710164239-da123dc03ef4',
title: 'Coffee table',
},
];
```
## Image list with title bars
This example demonstrates the use of the `ImageListItemBar` to add an overlay to each item.
The overlay can accommodate a `title`, `subtitle` and secondary action - in this example an `IconButton`.
```tsx
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
import ImageListItemBar from '@mui/material/ImageListItemBar';
import ListSubheader from '@mui/material/ListSubheader';
import IconButton from '@mui/material/IconButton';
import InfoIcon from '@mui/icons-material/Info';
export default function TitlebarImageList() {
return (
December
{itemData.map((item) => (
}
/>
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1551963831-b3b1ca40c98e',
title: 'Breakfast',
author: '@bkristastucchio',
rows: 2,
cols: 2,
featured: true,
},
{
img: 'https://images.unsplash.com/photo-1551782450-a2132b4ba21d',
title: 'Burger',
author: '@rollelflex_graphy726',
},
{
img: 'https://images.unsplash.com/photo-1522770179533-24471fcdba45',
title: 'Camera',
author: '@helloimnik',
},
{
img: 'https://images.unsplash.com/photo-1444418776041-9c7e33cc5a9c',
title: 'Coffee',
author: '@nolanissac',
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1533827432537-70133748f5c8',
title: 'Hats',
author: '@hjrc33',
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1558642452-9d2a7deb7f62',
title: 'Honey',
author: '@arwinneil',
rows: 2,
cols: 2,
featured: true,
},
{
img: 'https://images.unsplash.com/photo-1516802273409-68526ee1bdd6',
title: 'Basketball',
author: '@tjdragotta',
},
{
img: 'https://images.unsplash.com/photo-1518756131217-31eb79b20e8f',
title: 'Fern',
author: '@katie_wasserman',
},
{
img: 'https://images.unsplash.com/photo-1597645587822-e99fa5d45d25',
title: 'Mushrooms',
author: '@silverdalex',
rows: 2,
cols: 2,
},
{
img: 'https://images.unsplash.com/photo-1567306301408-9b74779a11af',
title: 'Tomato basil',
author: '@shelleypauls',
},
{
img: 'https://images.unsplash.com/photo-1471357674240-e1a485acb3e1',
title: 'Sea star',
author: '@peterlaster',
},
{
img: 'https://images.unsplash.com/photo-1589118949245-7d38baf380d6',
title: 'Bike',
author: '@southside_customs',
cols: 2,
},
];
```
### Title bar below image (standard)
The title bar can be placed below the image.
```tsx
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
import ImageListItemBar from '@mui/material/ImageListItemBar';
export default function TitlebarBelowImageList() {
return (
{itemData.map((item) => (
by: {item.author}}
position="below"
/>
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1551963831-b3b1ca40c98e',
title: 'Breakfast',
author: '@bkristastucchio',
},
{
img: 'https://images.unsplash.com/photo-1551782450-a2132b4ba21d',
title: 'Burger',
author: '@rollelflex_graphy726',
},
{
img: 'https://images.unsplash.com/photo-1522770179533-24471fcdba45',
title: 'Camera',
author: '@helloimnik',
},
{
img: 'https://images.unsplash.com/photo-1444418776041-9c7e33cc5a9c',
title: 'Coffee',
author: '@nolanissac',
},
{
img: 'https://images.unsplash.com/photo-1533827432537-70133748f5c8',
title: 'Hats',
author: '@hjrc33',
},
{
img: 'https://images.unsplash.com/photo-1558642452-9d2a7deb7f62',
title: 'Honey',
author: '@arwinneil',
},
{
img: 'https://images.unsplash.com/photo-1516802273409-68526ee1bdd6',
title: 'Basketball',
author: '@tjdragotta',
},
{
img: 'https://images.unsplash.com/photo-1518756131217-31eb79b20e8f',
title: 'Fern',
author: '@katie_wasserman',
},
{
img: 'https://images.unsplash.com/photo-1597645587822-e99fa5d45d25',
title: 'Mushrooms',
author: '@silverdalex',
},
{
img: 'https://images.unsplash.com/photo-1567306301408-9b74779a11af',
title: 'Tomato basil',
author: '@shelleypauls',
},
{
img: 'https://images.unsplash.com/photo-1471357674240-e1a485acb3e1',
title: 'Sea star',
author: '@peterlaster',
},
{
img: 'https://images.unsplash.com/photo-1589118949245-7d38baf380d6',
title: 'Bike',
author: '@southside_customs',
},
];
```
### Title bar below image (masonry)
```tsx
import Box from '@mui/material/Box';
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
import ImageListItemBar from '@mui/material/ImageListItemBar';
export default function TitlebarBelowMasonryImageList() {
return (
{itemData.map((item) => (
))}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1549388604-817d15aa0110',
title: 'Bed',
author: 'swabdesign',
},
{
img: 'https://images.unsplash.com/photo-1525097487452-6278ff080c31',
title: 'Books',
author: 'Pavel Nekoranec',
},
{
img: 'https://images.unsplash.com/photo-1523413651479-597eb2da0ad6',
title: 'Sink',
author: 'Charles Deluvio',
},
{
img: 'https://images.unsplash.com/photo-1563298723-dcfebaa392e3',
title: 'Kitchen',
author: 'Christian Mackie',
},
{
img: 'https://images.unsplash.com/photo-1588436706487-9d55d73a39e3',
title: 'Blinds',
author: 'Darren Richardson',
},
{
img: 'https://images.unsplash.com/photo-1574180045827-681f8a1a9622',
title: 'Chairs',
author: 'Taylor Simpson',
},
{
img: 'https://images.unsplash.com/photo-1530731141654-5993c3016c77',
title: 'Laptop',
author: 'Ben Kolde',
},
{
img: 'https://images.unsplash.com/photo-1481277542470-605612bd2d61',
title: 'Doors',
author: 'Philipp Berndt',
},
{
img: 'https://images.unsplash.com/photo-1517487881594-2787fef5ebf7',
title: 'Coffee',
author: 'Jen P.',
},
{
img: 'https://images.unsplash.com/photo-1516455207990-7a41ce80f7ee',
title: 'Storage',
author: 'Douglas Sheppard',
},
{
img: 'https://images.unsplash.com/photo-1597262975002-c5c3b14bbd62',
title: 'Candle',
author: 'Fi Bell',
},
{
img: 'https://images.unsplash.com/photo-1519710164239-da123dc03ef4',
title: 'Coffee table',
author: 'Hutomo Abrianto',
},
];
```
## Custom image list
In this example the items have a customized titlebar, positioned at the top and with a custom gradient `titleBackground`.
The secondary action `IconButton` is positioned on the left. The `gap` prop is used to adjust the gap between items.
```tsx
import ImageList from '@mui/material/ImageList';
import ImageListItem from '@mui/material/ImageListItem';
import ImageListItemBar from '@mui/material/ImageListItemBar';
import IconButton from '@mui/material/IconButton';
import StarBorderIcon from '@mui/icons-material/StarBorder';
function srcset(image: string, width: number, height: number, rows = 1, cols = 1) {
return {
src: `${image}?w=${width * cols}&h=${height * rows}&fit=crop&auto=format`,
srcSet: `${image}?w=${width * cols}&h=${
height * rows
}&fit=crop&auto=format&dpr=2 2x`,
};
}
export default function CustomImageList() {
return (
{itemData.map((item) => {
const cols = item.featured ? 2 : 1;
const rows = item.featured ? 2 : 1;
return (
}
actionPosition="left"
/>
);
})}
);
}
const itemData = [
{
img: 'https://images.unsplash.com/photo-1551963831-b3b1ca40c98e',
title: 'Breakfast',
author: '@bkristastucchio',
featured: true,
},
{
img: 'https://images.unsplash.com/photo-1551782450-a2132b4ba21d',
title: 'Burger',
author: '@rollelflex_graphy726',
},
{
img: 'https://images.unsplash.com/photo-1522770179533-24471fcdba45',
title: 'Camera',
author: '@helloimnik',
},
{
img: 'https://images.unsplash.com/photo-1444418776041-9c7e33cc5a9c',
title: 'Coffee',
author: '@nolanissac',
},
{
img: 'https://images.unsplash.com/photo-1533827432537-70133748f5c8',
title: 'Hats',
author: '@hjrc33',
},
{
img: 'https://images.unsplash.com/photo-1558642452-9d2a7deb7f62',
title: 'Honey',
author: '@arwinneil',
featured: true,
},
{
img: 'https://images.unsplash.com/photo-1516802273409-68526ee1bdd6',
title: 'Basketball',
author: '@tjdragotta',
},
{
img: 'https://images.unsplash.com/photo-1518756131217-31eb79b20e8f',
title: 'Fern',
author: '@katie_wasserman',
},
{
img: 'https://images.unsplash.com/photo-1597645587822-e99fa5d45d25',
title: 'Mushrooms',
author: '@silverdalex',
},
{
img: 'https://images.unsplash.com/photo-1567306301408-9b74779a11af',
title: 'Tomato basil',
author: '@shelleypauls',
},
{
img: 'https://images.unsplash.com/photo-1471357674240-e1a485acb3e1',
title: 'Sea star',
author: '@peterlaster',
},
{
img: 'https://images.unsplash.com/photo-1589118949245-7d38baf380d6',
title: 'Bike',
author: '@southside_customs',
},
];
```
# ImageList API
## Demos
For examples and details on the usage of this React component, visit the component demo pages:
- [Image List](https://mui.com/material-ui/react-image-list/)
## Import
```jsx
import ImageList from '@mui/material/ImageList';
// or
import { ImageList } from '@mui/material';
```
## Props
| Name | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| children | `node` | - | Yes | |
| classes | `object` | - | No | Override or extend the styles applied to the component. |
| cols | `integer` | `2` | No | |
| component | `elementType` | - | No | |
| gap | `number` | `4` | No | |
| rowHeight | `'auto' \| number` | `'auto'` | No | |
| sx | `Array \| func \| object` | - | No | The system prop that allows defining system overrides as well as additional CSS styles. |
| variant | `'masonry' \| 'quilted' \| 'standard' \| 'woven' \| string` | `'standard'` | No | |
> **Note**: The `ref` is forwarded to the root element (HTMLUListElement).
> Any other props supplied will be provided to the root element (native element).
## Theme default props
You can use `MuiImageList` to change the default props of this component with the theme.
## CSS
### Rule name
| Global class | Rule name | Description |
|--------------|-----------|-------------|
| - | masonry | Styles applied to the root element if `variant="masonry"`. |
| - | quilted | Styles applied to the root element if `variant="quilted"`. |
| - | root | Styles applied to the root element. |
| - | standard | Styles applied to the root element if `variant="standard"`. |
| - | woven | Styles applied to the root element if `variant="woven"`. |
## Source code
If you did not find the information on this page, consider having a look at the implementation of the component for more detail.
- [/packages/mui-material/src/ImageList/ImageList.js](https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/ImageList/ImageList.js)
# ImageListItem API
## Demos
For examples and details on the usage of this React component, visit the component demo pages:
- [Image List](https://mui.com/material-ui/react-image-list/)
## Import
```jsx
import ImageListItem from '@mui/material/ImageListItem';
// or
import { ImageListItem } from '@mui/material';
```
## Props
| Name | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| children | `node` | - | No | |
| classes | `object` | - | No | Override or extend the styles applied to the component. |
| cols | `integer` | `1` | No | |
| component | `elementType` | - | No | |
| rows | `integer` | `1` | No | |
| sx | `Array \| func \| object` | - | No | The system prop that allows defining system overrides as well as additional CSS styles. |
> **Note**: The `ref` is forwarded to the root element (HTMLLIElement).
> Any other props supplied will be provided to the root element (native element).
## Theme default props
You can use `MuiImageListItem` to change the default props of this component with the theme.
## CSS
### Rule name
| Global class | Rule name | Description |
|--------------|-----------|-------------|
| - | img | Styles applied to an `img` element to ensure it covers the item. |
| - | masonry | Styles applied to the root element if `variant="masonry"`. |
| - | quilted | Styles applied to the root element if `variant="quilted"`. |
| - | root | Styles applied to the root element. |
| - | standard | Styles applied to the root element if `variant="standard"`. |
| - | woven | Styles applied to the root element if `variant="woven"`. |
## Source code
If you did not find the information on this page, consider having a look at the implementation of the component for more detail.
- [/packages/mui-material/src/ImageListItem/ImageListItem.js](https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/ImageListItem/ImageListItem.js)
# ImageListItemBar API
## Demos
For examples and details on the usage of this React component, visit the component demo pages:
- [Image List](https://mui.com/material-ui/react-image-list/)
## Import
```jsx
import ImageListItemBar from '@mui/material/ImageListItemBar';
// or
import { ImageListItemBar } from '@mui/material';
```
## Props
| Name | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| actionIcon | `node` | - | No | |
| actionPosition | `'left' \| 'right'` | `'right'` | No | |
| classes | `object` | - | No | Override or extend the styles applied to the component. |
| position | `'below' \| 'bottom' \| 'top'` | `'bottom'` | No | |
| subtitle | `node` | - | No | |
| sx | `Array \| func \| object` | - | No | The system prop that allows defining system overrides as well as additional CSS styles. |
| title | `node` | - | No | |
> **Note**: The `ref` is forwarded to the root element (HTMLDivElement).
> Any other props supplied will be provided to the root element (native element).
## Theme default props
You can use `MuiImageListItemBar` to change the default props of this component with the theme.
## CSS
### Rule name
| Global class | Rule name | Description |
|--------------|-----------|-------------|
| - | actionIcon | Styles applied to the actionIcon if supplied. |
| - | actionPositionLeft | Styles applied to the action container element if `actionPosition="left"`. |
| - | actionPositionRight | Styles applied to the action container element if `actionPosition="right"`. |
| - | positionBelow | Styles applied to the root element if `position="below"`. |
| - | positionBottom | Styles applied to the root element if `position="bottom"`. |
| - | positionTop | Styles applied to the root element if `position="top"`. |
| - | root | Styles applied to the root element. |
| - | subtitle | Styles applied to the subtitle container element. |
| - | title | Styles applied to the title container element. |
| - | titleWrap | Styles applied to the title and subtitle container element. |
## Source code
If you did not find the information on this page, consider having a look at the implementation of the component for more detail.
- [/packages/mui-material/src/ImageListItemBar/ImageListItemBar.js](https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/ImageListItemBar/ImageListItemBar.js)