Collage

View source on GitHub

; Opens a new tab

Collage, similarly to Masonry, creates a deterministic grid layout that can absolutely position and virtualize images.

also known as Photo Composition

Figma:

Web:

iOS:

Android:

A11y:

Props

Component props
Name	Type	Default
`columns` Required	`2 \| 3 \| 4`	-
	Number of columns (2 - 4). Note that Collage assumes at least 2 * `columns` images will be provided. If fewer images are provided, care will be needed to avoid TypeErrors. See Columns example for more details.
`height` Required	`number`	-
	Height of the collage.
`renderImage` Required	`({\| width: number, height: number, index: number, \|}) => React.Node`	-
	Callback to render the collage images.
`width` Required	`number`	-
	Width of the collage.
`cover`	`boolean`	-
	Whether or not the first image is a cover image. See Cover Image example for more details.
`gutter`	`number`	-
	The amount of vertical and horizontal space between images. See Gutter example for more details.
`layoutKey`	`number`	-
	Depending on the number of columns of the collage, there may be multiple layouts available. If there are N layouts available, (layoutKey % N) will determine which layout is used. See Layout Key example for more details.

Basic example

<Collage
  columns={3}
  height={300}
  width={300}
  renderImage={({ index, width, height }) => {
    const images = [
      {
        color: 'rgb(111, 91, 77)',
        naturalHeight: 751,
        naturalWidth: 564,
        src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
      },
      {
        color: 'rgb(231, 186, 176)',
        naturalHeight: 200,
        naturalWidth: 98,
        src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
      },
      {
        color: '#000',
        naturalHeight: 300,
        naturalWidth: 200,
        src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
      },
      {
        color: '#000',
        naturalHeight: 517,
        naturalWidth: 564,
        src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
      },
      {
        color: '#000',
        naturalHeight: 806,
        naturalWidth: 564,
        src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
      },
      {
        color: '#000',
        naturalHeight: 200,
        naturalWidth: 200,
        src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
      },
    ];
    const image = images[index] || {};
    return (
      <Mask wash width={width} height={height}>
        <Image
          alt="collage image"
          color={image.color}
          fit="cover"
          naturalHeight={image.naturalHeight}
          naturalWidth={image.naturalWidth}
          src={image.src}
        />
      </Mask>
    );
  }}
/>

<Collage
  columns={3}
  height={300}
  width={300}
  renderImage={({ index, width, height }) => {
    const images = [
      {
        color: 'rgb(111, 91, 77)',
        naturalHeight: 751,
        naturalWidth: 564,
        src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
      },
      {
        color: 'rgb(231, 186, 176)',
        naturalHeight: 200,
        naturalWidth: 98,
        src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
      },
      {
        color: '#000',
        naturalHeight: 300,
        naturalWidth: 200,
        src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
      },
      {
        color: '#000',
        naturalHeight: 517,
        naturalWidth: 564,
        src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
      },
      {
        color: '#000',
        naturalHeight: 806,
        naturalWidth: 564,
        src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
      },
      {
        color: '#000',
        naturalHeight: 200,
        naturalWidth: 200,
        src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
      },
    ];
    const image = images[index] || {};
    return (
      <Mask wash width={width} height={height}>
        <Image
          alt="collage image"
          color={image.color}
          fit="cover"
          naturalHeight={image.naturalHeight}
          naturalWidth={image.naturalWidth}
          src={image.src}
        />
      </Mask>
    );
  }}
/>

Accessibility

Ready

Variants

Different columns

2 - 4 columns

<Flex wrap>
  {[2, 3, 4].map((columns) => (
    <Box key={columns} padding={2}>
      <Box>
        <Text>
          columns = {columns}
        </Text>
      </Box>

      <Collage
        columns={columns}
        height={150}
        width={150}
        renderImage={({ index, width, height }) => {
          const images = [
            {
              color: 'rgb(111, 91, 77)',
              naturalHeight: 751,
              naturalWidth: 564,
              src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
            },
            {
              color: 'rgb(231, 186, 176)',
              naturalHeight: 200,
              naturalWidth: 98,
              src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
            },
            {
              color: '#000',
              naturalHeight: 300,
              naturalWidth: 200,
              src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
            },
            {
              color: '#000',
              naturalHeight: 517,
              naturalWidth: 564,
              src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
            },
            {
              color: '#000',
              naturalHeight: 806,
              naturalWidth: 564,
              src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
            },
            {
              color: '#000',
              naturalHeight: 200,
              naturalWidth: 200,
              src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
            },
          ];
          const image = images[index] || {};
          return (
            <Mask wash width={width} height={height}>
              {image.src ? (
                <Image
                  alt="collage image"
                  color={image.color}
                  fit="cover"
                  naturalHeight={image.naturalHeight}
                  naturalWidth={image.naturalWidth}
                  src={image.src}
                />
              ) : (
                <Box
                  color="lightGray"
                  height={height}
                  width={width}
                />
              )}
            </Mask>
          );
        }}
      />
    </Box>
  ))}
</Flex>

<Flex wrap>
  {[2, 3, 4].map((columns) => (
    <Box key={columns} padding={2}>
      <Box>
        <Text>
          columns = {columns}
        </Text>
      </Box>

      <Collage
        columns={columns}
        height={150}
        width={150}
        renderImage={({ index, width, height }) => {
          const images = [
            {
              color: 'rgb(111, 91, 77)',
              naturalHeight: 751,
              naturalWidth: 564,
              src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
            },
            {
              color: 'rgb(231, 186, 176)',
              naturalHeight: 200,
              naturalWidth: 98,
              src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
            },
            {
              color: '#000',
              naturalHeight: 300,
              naturalWidth: 200,
              src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
            },
            {
              color: '#000',
              naturalHeight: 517,
              naturalWidth: 564,
              src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
            },
            {
              color: '#000',
              naturalHeight: 806,
              naturalWidth: 564,
              src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
            },
            {
              color: '#000',
              naturalHeight: 200,
              naturalWidth: 200,
              src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
            },
          ];
          const image = images[index] || {};
          return (
            <Mask wash width={width} height={height}>
              {image.src ? (
                <Image
                  alt="collage image"
                  color={image.color}
                  fit="cover"
                  naturalHeight={image.naturalHeight}
                  naturalWidth={image.naturalWidth}
                  src={image.src}
                />
              ) : (
                <Box
                  color="lightGray"
                  height={height}
                  width={width}
                />
              )}
            </Mask>
          );
        }}
      />
    </Box>
  ))}
</Flex>

Gutter

<Box color="gray" width={300} height={300}>
  <Collage
    columns={3}
    gutter={8}
    height={300}
    width={300}
    renderImage={({ index, width, height }) => {
      const images = [
        {
          color: 'rgb(111, 91, 77)',
          naturalHeight: 751,
          naturalWidth: 564,
          src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
        },
        {
          color: 'rgb(231, 186, 176)',
          naturalHeight: 200,
          naturalWidth: 98,
          src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
        },
        {
          color: '#000',
          naturalHeight: 300,
          naturalWidth: 200,
          src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
        },
        {
          color: '#000',
          naturalHeight: 517,
          naturalWidth: 564,
          src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
        },
        {
          color: '#000',
          naturalHeight: 806,
          naturalWidth: 564,
          src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
        },
        {
          color: '#000',
          naturalHeight: 200,
          naturalWidth: 200,
          src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
        },
      ];
      const image = images[index] || {};
      return (
        <Mask wash width={width} height={height}>
          <Image
            alt="collage image"
            color={image.color}
            fit="cover"
            naturalHeight={image.naturalHeight}
            naturalWidth={image.naturalWidth}
            src={image.src}
          />
        </Mask>
      );
    }}
  />
</Box>

<Box color="gray" width={300} height={300}>
  <Collage
    columns={3}
    gutter={8}
    height={300}
    width={300}
    renderImage={({ index, width, height }) => {
      const images = [
        {
          color: 'rgb(111, 91, 77)',
          naturalHeight: 751,
          naturalWidth: 564,
          src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
        },
        {
          color: 'rgb(231, 186, 176)',
          naturalHeight: 200,
          naturalWidth: 98,
          src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
        },
        {
          color: '#000',
          naturalHeight: 300,
          naturalWidth: 200,
          src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
        },
        {
          color: '#000',
          naturalHeight: 517,
          naturalWidth: 564,
          src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
        },
        {
          color: '#000',
          naturalHeight: 806,
          naturalWidth: 564,
          src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
        },
        {
          color: '#000',
          naturalHeight: 200,
          naturalWidth: 200,
          src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
        },
      ];
      const image = images[index] || {};
      return (
        <Mask wash width={width} height={height}>
          <Image
            alt="collage image"
            color={image.color}
            fit="cover"
            naturalHeight={image.naturalHeight}
            naturalWidth={image.naturalWidth}
            src={image.src}
          />
        </Mask>
      );
    }}
  />
</Box>

Cover image

<Box color="gray" width={300} height={300}>
  <Collage
    columns={3}
    cover
    height={300}
    gutter={8}
    renderImage={({ index, width, height }) => {
      const coverImage = {
        color: '#000',
        naturalHeight: 806,
        naturalWidth: 564,
        src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
      };
      const nonCoverImages = [
        {
          color: 'rgb(111, 91, 77)',
          naturalHeight: 751,
          naturalWidth: 564,
          src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
        },
        {
          color: 'rgb(231, 186, 176)',
          naturalHeight: 200,
          naturalWidth: 98,
          src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
        },
      ];
      const image = index === 0 ? coverImage : nonCoverImages[index - 1];
      return (
        <Mask width={width} height={height}>
          <Image
            alt="cover image"
            src={image.src}
            color={image.color}
            naturalHeight={image.naturalHeight}
            naturalWidth={image.naturalWidth}
            fit="cover"
          />
        </Mask>
      );
    }}
    width={300}
  />
</Box>

<Box color="gray" width={300} height={300}>
  <Collage
    columns={3}
    cover
    height={300}
    gutter={8}
    renderImage={({ index, width, height }) => {
      const coverImage = {
        color: '#000',
        naturalHeight: 806,
        naturalWidth: 564,
        src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
      };
      const nonCoverImages = [
        {
          color: 'rgb(111, 91, 77)',
          naturalHeight: 751,
          naturalWidth: 564,
          src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
        },
        {
          color: 'rgb(231, 186, 176)',
          naturalHeight: 200,
          naturalWidth: 98,
          src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
        },
      ];
      const image = index === 0 ? coverImage : nonCoverImages[index - 1];
      return (
        <Mask width={width} height={height}>
          <Image
            alt="cover image"
            src={image.src}
            color={image.color}
            naturalHeight={image.naturalHeight}
            naturalWidth={image.naturalWidth}
            fit="cover"
          />
        </Mask>
      );
    }}
    width={300}
  />
</Box>

Different columns with cover image

2 - 4 columns with cover image

<Flex wrap>
  {[2, 3, 4].map((columns) => (
    <Box key={columns} padding={2}>
      <Box>
        <Text>
          columns = {columns}
        </Text>
      </Box>

      <Collage
        columns={columns}
        cover
        height={150}
        width={150}
        renderImage={({ index, width, height }) => {
          const images = [
            {
              color: 'rgb(111, 91, 77)',
              naturalHeight: 751,
              naturalWidth: 564,
              src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
            },
            {
              color: 'rgb(231, 186, 176)',
              naturalHeight: 200,
              naturalWidth: 98,
              src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
            },
            {
              color: '#000',
              naturalHeight: 300,
              naturalWidth: 200,
              src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
            },
            {
              color: '#000',
              naturalHeight: 517,
              naturalWidth: 564,
              src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
            },
            {
              color: '#000',
              naturalHeight: 806,
              naturalWidth: 564,
              src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
            },
            {
              color: '#000',
              naturalHeight: 200,
              naturalWidth: 200,
              src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
            },
          ];
          const image = images[index] || {};
          return (
            <Mask wash width={width} height={height}>
              {image.src ? (
                <Image
                  alt="collage image"
                  color={image.color}
                  fit="cover"
                  naturalHeight={image.naturalHeight}
                  naturalWidth={image.naturalWidth}
                  src={image.src}
                />
              ) : (
                <Box
                  color="lightGray"
                  height={height}
                  width={width}
                />
              )}
            </Mask>
          );
        }}
      />
    </Box>
  ))}
</Flex>

<Flex wrap>
  {[2, 3, 4].map((columns) => (
    <Box key={columns} padding={2}>
      <Box>
        <Text>
          columns = {columns}
        </Text>
      </Box>

      <Collage
        columns={columns}
        cover
        height={150}
        width={150}
        renderImage={({ index, width, height }) => {
          const images = [
            {
              color: 'rgb(111, 91, 77)',
              naturalHeight: 751,
              naturalWidth: 564,
              src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
            },
            {
              color: 'rgb(231, 186, 176)',
              naturalHeight: 200,
              naturalWidth: 98,
              src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
            },
            {
              color: '#000',
              naturalHeight: 300,
              naturalWidth: 200,
              src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
            },
            {
              color: '#000',
              naturalHeight: 517,
              naturalWidth: 564,
              src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
            },
            {
              color: '#000',
              naturalHeight: 806,
              naturalWidth: 564,
              src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
            },
            {
              color: '#000',
              naturalHeight: 200,
              naturalWidth: 200,
              src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
            },
          ];
          const image = images[index] || {};
          return (
            <Mask wash width={width} height={height}>
              {image.src ? (
                <Image
                  alt="collage image"
                  color={image.color}
                  fit="cover"
                  naturalHeight={image.naturalHeight}
                  naturalWidth={image.naturalWidth}
                  src={image.src}
                />
              ) : (
                <Box
                  color="lightGray"
                  height={height}
                  width={width}
                />
              )}
            </Mask>
          );
        }}
      />
    </Box>
  ))}
</Flex>

Layout key

You can pick a layout using the layout key (layout key is 0 by default). Depending on the number of columns of the collage, there may be multiple layouts available. If there are N layouts available, (layoutKey % N) will determine which layout is used.

<Flex wrap>
  {[0, 1, 2, 3].map((layoutKey) => (
    <Box key={layoutKey} padding={2}>
      <Box>
        <Text>
          layoutKey = {layoutKey}
        </Text>
      </Box>

      <Collage
        columns={3}
        height={150}
        width={150}
        layoutKey={layoutKey}
        renderImage={({ index, width, height }) => {
          const images = [
            {
              color: 'rgb(111, 91, 77)',
              naturalHeight: 751,
              naturalWidth: 564,
              src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
            },
            {
              color: 'rgb(231, 186, 176)',
              naturalHeight: 200,
              naturalWidth: 98,
              src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
            },
            {
              color: '#000',
              naturalHeight: 300,
              naturalWidth: 200,
              src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
            },
            {
              color: '#000',
              naturalHeight: 517,
              naturalWidth: 564,
              src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
            },
            {
              color: '#000',
              naturalHeight: 806,
              naturalWidth: 564,
              src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
            },
            {
              color: '#000',
              naturalHeight: 200,
              naturalWidth: 200,
              src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
            },
          ];
          const image = images[index] || {};
          return (
            <Mask wash width={width} height={height}>
              <Image
                alt="collage image"
                color={image.color}
                fit="cover"
                naturalHeight={image.naturalHeight}
                naturalWidth={image.naturalWidth}
                src={image.src}
              />
            </Mask>
          );
        }}
      />
    </Box>
  ))}
</Flex>

<Flex wrap>
  {[0, 1, 2, 3].map((layoutKey) => (
    <Box key={layoutKey} padding={2}>
      <Box>
        <Text>
          layoutKey = {layoutKey}
        </Text>
      </Box>

      <Collage
        columns={3}
        height={150}
        width={150}
        layoutKey={layoutKey}
        renderImage={({ index, width, height }) => {
          const images = [
            {
              color: 'rgb(111, 91, 77)',
              naturalHeight: 751,
              naturalWidth: 564,
              src: 'https://i.ibb.co/Lx54BCT/stock1.jpg',
            },
            {
              color: 'rgb(231, 186, 176)',
              naturalHeight: 200,
              naturalWidth: 98,
              src: 'https://i.ibb.co/7bQQYkX/stock2.jpg',
            },
            {
              color: '#000',
              naturalHeight: 300,
              naturalWidth: 200,
              src: 'https://i.ibb.co/d0pQsJz/stock3.jpg',
            },
            {
              color: '#000',
              naturalHeight: 517,
              naturalWidth: 564,
              src: 'https://i.ibb.co/SB0pXgS/stock4.jpg',
            },
            {
              color: '#000',
              naturalHeight: 806,
              naturalWidth: 564,
              src: 'https://i.ibb.co/jVR29XV/stock5.jpg',
            },
            {
              color: '#000',
              naturalHeight: 200,
              naturalWidth: 200,
              src: 'https://i.ibb.co/FY2MKr5/stock6.jpg',
            },
          ];
          const image = images[index] || {};
          return (
            <Mask wash width={width} height={height}>
              <Image
                alt="collage image"
                color={image.color}
                fit="cover"
                naturalHeight={image.naturalHeight}
                naturalWidth={image.naturalWidth}
                src={image.src}
              />
            </Mask>
          );
        }}
      />
    </Box>
  ))}
</Flex>

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library		Component is not currently available in Figma.
Responsive Web	Ready	Component is available in code for web and mobile web.
iOS		Component is not currently available in code for iOS.
Android		Component is not currently available in code for Android.

Edit page on GitHub

; Opens a new tab