# Retrospective on Implementing a Masonry Layout for Our Service
> Let's neatly stack portfolios of all different sizes.
- Published: 2025-07-24
- Source: https://yujiseok.blog/en/posts/how-to-implement-portfolio
## Overview
[Portfolio](https://coloso.co.kr/portfolio) is a showcase service that gathers creators' portfolios and career histories in one place.
Its main goals were to spend marketing budget efficiently and to draw in more potential customers.
To get there, it wasn't enough to simply display works. We needed to bring out each creator's brand value and strengthen the UI so customers could reach content easily.
Because visual variety and information density matter so much for this kind of service, one of the key requirements was to adopt a Masonry layout to maximize the user experience.
In this post, I'll go over how I actually implemented the Masonry layout in the Portfolio service, along with the thoughts I had along the way.
## What is Masonry?
Pinterest's Masonry layout
Before building the UI, I did a bit of research on the Masonry layout.
**Masonry** is defined as follows:
- A structure built by stacking individual units such as bricks or stones
- It means "**bricklaying**" or "**stonework**", referring to the craft of stacking bricks or stones, or the result of it
Borrowing this structural idea, a layout on the web where multiple elements (cards, images, etc.) are stacked naturally with no gaps, like bricks, is called a "**Masonry layout**".
## Strengths of the Masonry Layout
So what are the characteristics of a Masonry layout, and what do we gain from it?
### 1. Maximized use of space
- Items of irregular size (images, cards, etc.) are placed with no gaps, minimizing unused space on the screen
- In large-scale image/portfolio services, it maximizes scroll efficiency and information density
### 2. Visual variety and dynamic expression
- Each element stacks freely, giving the screen rhythm and vitality
- Unlike a rigid grid, Masonry offers a fresh experience through an irregular yet flexible arrangement
### 3. Responsiveness and scalability
- A Masonry layout can automatically adjust the number of columns and the placement as the screen size changes, guaranteeing a consistent UX on every device, whether mobile, tablet, or desktop
- Even when content is added or removed dynamically, the layout rearranges itself naturally, making it a good fit for real-time feeds and infinite-scroll environments
### 4. Adaptability to image sizes
- Images with irregular heights can still be stacked naturally, which is ideal for displaying portfolios/works/images of various sizes
- It preserves each image's own ratio and size while achieving both space efficiency and visual polish
### 5. UX and business impact
- First impression: Masonry exposes a wide variety of content at a glance, boosting user interest and time spent
- Browsing efficiency: Users can explore more content quickly, which improves conversion and return visits
- Brand differentiation: It offers a visual style distinct from a card grid, improving brand recognition and trust
Thanks to these strengths, the Masonry layout was the most effective way to meet the visual requirements of the portfolio service,
and I designed the overall screen structure around it.
## Initial Implementation
In the early stage, I had a vague feeling that I could just do this with CSS.
I had a [past experience](https://www.yujiseok.blog/music/playlists) of building something with pure CSS on my blog, so this time too I wanted to try the grid layout system and implement it with pure CSS.
> I somehow got stubborn about proving CSS could do it..π€£
### Trying it with grid
Grid is a layout system that lets you build two-dimensional layouts, placing items in rows and columns.
Here, you can use grid's `grid-row` property to specify an item's row position.
This property lets an individual item span multiple rows, and you can use span to set how many rows it takes up.
For simple layouts with no policies, there were no real problems,
but once detailed policies came into play, such as **the number of columns per viewport**, **item sizes**, and **gaps**, the limits of a CSS implementation became clear.
### Why is the grid-row approach alone not enough for a Masonry layout?
1. The limits of row-based placement
- With grid-row, you can only place things in units of "**rows (a sum of rows)**".
β Even if each card has a different height, it always has to share rows with the cards next to it
β As a result, some cards end up with unintended empty space, and Masonry's signature "**naturally interlocking stack**" becomes impossible.
2. Item height is determined automatically
- If the row heights in a grid container are explicitly defined, each item's actual height is determined automatically by them.
- ```css title="grid-row.css"
.container {
display: grid;
grid-template-rows: 100px 200px 150px;
}
.item {
grid-row: span 2; /* 2 row κ±Έμ³ λ°°μΉ */
}
```
(With an explicit grid definition like the `CSS` code above, the height of `.item` is determined as the sum of 2 rows, `100px + 200px = 300px`.)
> An explicit grid is one where the developer clearly specifies the rows and columns, while an implicit grid is one where the browser decides the rows and columns automatically.
3. No fine-grained control over individual item heights
- Even if you set a desired height on each item, the grid system's row heights and span rules take priority, so the actual placement can differ from what you intended.
- For example, if the height of the 3rd item in the misaligned layout above is set to `476px`, that entire row gets fixed to `476px`. Because of this, even if the 2nd item is set to `274px`, empty space appears and the layout goes out of alignment.
For a simple demo or prototype stage, it was good enough to roughly imitate a Masonry layout, but it fell short of meeting the complex requirements of a real production service.
So I accepted that building a Masonry-style layout with pure CSS alone was unrealistic, and reset my direction for the actual implementation.
## What I Needed Before Implementing
### Example policy
Viewport
{'~719px'}
{'720px~959px'}
{'960px~1279px'}
{'1280px~1727px'}
...
Grid columns
2
3
4
4
Grid max-width
1120px
1120px
1688px
Grid min-width
1120px
Container min-width
320px
680px
890px
1120px
Container max-width
679px
889px
1119px
1495px
Grid gap x
12px
16px
16px
16px
Grid gap y
16px
18px
18px
20px
Item min-width
154px
216px
210.5px
240px
Item max-width
268px
268px
268px
Item min-height
60px
145px
145px
145px
Item max-height
274px
476px
476px
448px
In the real service, as the table above shows, complex policies are required: the number of columns per viewport, container width, item width, item height, and so on.
### Finding a reference
While researching references for implementing the Masonry layout policy, I judged that the structure of [Pinterest](https://www.pinterest.com) fit the service's requirements best, so I decided to build on it.
);
};
export default Masonry;
```
I use the values returned from `getMasonryOptions` to place the items in the actual Masonry component. I used the render prop pattern so the component can focus purely on layout placement.
To position the items, I used the `translate3d` property.
### Why did I use translate3d?
`translate3d`, unlike the regular `translate` property, forcibly enables hardware acceleration. This brings the following performance benefits:
1. **GPU-accelerated rendering**
- The browser promotes the element to its own layer and handles it directly on the GPU
- It uses the GPU's parallel processing power instead of the CPU for faster rendering
2. **Minimized reflow**
- `translate3d` is a transform that doesn't affect layout
- Only that element moves, with no recalculation of other elements' positions
3. **Smooth animation**
- Guarantees smooth 60fps animation
- Especially helpful in a Masonry layout where many items move at once
- Improves scroll performance
4. **Memory efficiency**
- Stored as a texture in GPU memory, which reduces CPU memory usage
- Keeps performance consistent even in complex layouts
In a Masonry layout, hundreds of items are each placed at a different position, so this kind of performance optimization directly affects the user experience.
The finished component looks like this on screen:
> We now have a layout that's a perfect fit for showing off creators' portfolios. π¨
## Refactoring
After the actual implementation, I found a few things to improve and went through a refactoring.
### 1. Adding styles for image placement
I added styles to handle the image positioning that the policy called for.
The requirements were as follows:
- Pinned to the top
- Since there are lots of images like illustrations, the starting point could end up placed too high
- For character illustrations, the head could get cut off
- Centered
- Crop the bottom
- If the image is taller than the existing policy's maxHeight, crop the bottom
I wondered how best to handle this kind of image placement policy, and it turned out I could implement it simply with the `object-position` property.
The object-position property lets you specify where the image is positioned.
```css
object-position: center top;
```
Applying this style to the image prevents heads from getting cut off.
Head cut off before applying object-position
Head intact after applying object-position
> Without that style, we might have ended up with a pretty gruesome portfolio service..? π«£
### 2. Applying virtual scrolling
Virtual scrolling (windowing) is a performance optimization technique for efficiently rendering large amounts of data.
The core idea is to render only the items within the screen the user is looking at (the viewport) in the DOM, and remove items that have scrolled out of view from the DOM.
I had virtual scrolling in mind early in development, but at that point there wasn't much data, and I judged that building other features mattered more than adding virtual scrolling.
Later, as the amount of data kept growing, I decided virtual scrolling was necessary and applied it.
Rendering endlessly growing data entirely in the DOM causes performance degradation.
For example, with 10,000 items, rendering all of them in the DOM actually creates 10,000 DOM elements.
The more items there are, the more DOM nodes grow linearly, which can seriously hurt the browser's rendering performance and memory load.
#### Required work and values
Before applying virtual scrolling, I thought about how to approach the work and proceeded in the following steps.
- Calculate the latest `scrollY` value and the **viewport height** as the scroll position changes
- Based on that information, filter the array of items that should be shown on screen
To carry out the work above smoothly, a few values are needed.
1. `scrollY`
- The current window scroll position (window.scrollY)
- The basis for calculating which region to show the user
2. `viewportHeight`
- The current viewport height (window.innerHeight)
- The actual height of the screen the user can see
3. `bufferSize`
- Extra room to render above and below the screen
- To improve the experience during fast scrolling, it pre-renders items that haven't entered the screen yet
- Without a buffer, content might suddenly pop into view while scrolling
4. `masonryItems`
- An array of layout info for all the items to actually draw on screen
- Info on where (top) each item sits and how much height it takes up
5. Render range (`start`, `end`)
- The min/max region to actually render from the virtual list
- start = scrollY - bufferSize -> the start of the range of items to show, including the area just before what the user sees
- end = scrollY + viewportHeight + bufferSize -> the end of the range of items to show, including the buffer below the screen
Based on these values, we go through the item array, and if an item's actual position (itemTop, itemBottom) falls within the range, we render it.
#### Implementing the functions
Now let's look at the functions that do the actual work.
```ts title="useWindowing.ts"
import { useEffect, useRef, useState } from 'react';
const useWindowing = () => {
const [scrollY, setScrollY] = useState(0);
const viewportHeight = useRef(0);
const rafId = useRef(null);
useEffect(() => {
const update = () => {
setScrollY(window.scrollY);
viewportHeight.current = window.innerHeight;
rafId.current = null;
};
const handleEvent = () => {
if (rafId.current === null) {
rafId.current = window.requestAnimationFrame(update);
}
};
update();
window.addEventListener('scroll', handleEvent, { passive: true });
window.addEventListener('resize', handleEvent);
return () => {
window.removeEventListener('scroll', handleEvent);
window.removeEventListener('resize', handleEvent);
if (rafId.current !== null) {
window.cancelAnimationFrame(rafId.current);
}
};
}, []);
return { scrollY, viewportHeight: viewportHeight.current, bufferSize: viewportHeight.current / 2 };
};
export default useWindowing;
```
What `useWindowing` does is update `scrollY` to its latest value on scroll events and calculate the viewport height.
It returns `scrollY`, `viewportHeight`, and `bufferSize`, the values needed for virtual scrolling.
The function that uses those values to filter the items to show on screen and calculate the render range looks like this.
```ts
const windowingLayoutItems = ({ masonryItems, scrollY, viewportHeight, bufferSize }: WindowingLayoutOptions) => {
const start = scrollY - bufferSize; // μ μμμ ν¬ν¨ν΄ 보μ¬μ€ μμ΄ν μ μμ λ²μ
const end = scrollY + viewportHeight + bufferSize; // μλ μμμ ν¬ν¨ν΄ 보μ¬μ€ μμ΄ν μ λ λ²μ
return masonryItems.filter((layout) => {
const itemTop = layout.masonry.top;
const itemBottom = itemTop + layout.masonry.height;
return itemBottom >= start && itemTop <= end;
});
};
```
The `windowingLayoutItems` function filters items by their position info and returns the ones included in rendering.
Here it uses the position info (top, height) that was already computed during the Masonry layout calculation.
- `itemBottom >= start` -> the item's bottom is below the start of the screen range
- `itemTop <= end` -> the item's top is above the end of the screen range
If both conditions are true, we can treat the item as falling within the render range.
Based on the range calculated this way, we go through masonryItems and return, as an array, the items whose actual position (itemTop, itemBottom) falls within the start~end range.
```tsx title="Masonry.tsx"
'use client';
const Masonry = ({ items, renderItem, className, listType = 'main', isMobile }: MasonryProps) => {
// ... μλ΅
const viewport = useElementWidth();
const { scrollY, viewportHeight, bufferSize } = useWindowing();
const { masonryItems, masonryContainerHeight, columnWidth, centerOffset, policy } = getMasonryOptions({ containerWidth, items, listType, isMobile, viewport });
const visibleItems = windowingLayoutItems({ masonryItems, scrollY, viewportHeight, bufferSize });
return (
);
};
```
With virtual scrolling applied like this, instead of rendering as many items in the DOM as there is data, we now render only the items visible in the viewport (60-70 on average).
> Because each item's top value was already worked out in the Masonry layout calculation step,
> I could pick out the items to show in the viewport efficiently by reusing that value,
> with no extra position calculation when implementing virtual scrolling. βοΈ
#### Performance after the improvement
Without virtual scrolling
With virtual scrolling
Metric
Without virtual scrolling
With virtual scrolling
Reduction
Effect
Scripting
3.550ms
2.797ms
21.2%
Shorter JavaScript execution time
Rendering
0.864ms
0.460ms
46.8%
Rendering cost cut dramatically
Painting
0.339ms
0.174ms
48.7%
Painting load significantly reduced
System
1.804ms
1.217ms
32.5%
Better system-level performance
Main Thread Time
8.839ms
7.737ms
12.5%
Lower main thread load
Long task metric
Without virtual scrolling
With virtual scrolling
Reduction
Task duration
1.28s (self 36ΞΌs)
759.23ms (self 37ΞΌs)
40.7%
Browser blocking time
1.23s
709.23ms
42.3%
By applying virtual scrolling like this, we avoid performance degradation even as the data grows, and can deliver a smooth user experience.
### 3. Memoization
Memoization is a technique that stores previously computed results and reuses them when the same input comes in again.
This lets you avoid repeating the same calculation and improve performance.
After applying virtual scrolling, the scrollY state changes on every scroll movement,
which caused component rendering and the Masonry layout calculation to happen very frequently.
To minimize the unnecessary computation and rendering this caused, I introduced memoization to optimize performance.
#### Memoizing the `MasonryItem` component
First, I used React's `memo` function to reduce how often the component renders.
MasonryItem is the component that renders an individual item. It receives layout info as props and renders it.
```tsx title="MasonryItem.tsx"
import { memo } from 'react';
const MasonryItem = memo(
({ item, index, style, href, showLikeButton = true }) => {
// ...μλ΅
},
(prev, next) =>
prev.item.id === next.item.id &&
prev.index === next.index &&
prev.href === next.href &&
prev.style.height === next.style.height &&
prev.style.width === next.style.width &&
prev.style.transform === next.style.transform
);
MasonryItem.displayName = 'MasonryItem';
```
After wrapping MasonryItem with React.memo, I customized the props comparison function (`arePropsEqual`) so that it only re-renders when the key properties (item.id, index, href, style) change.
Applying memoization this way let me reduce the number of component renders. In numbers, it looks like this:
Item
Before (ms)
After (ms)
Reduction (%)
Total measured range
12,795ms
12,079ms
5.6%
Experience
8,327ms
6,439ms
22.7%
System
1,966ms
1,212ms
38.4%
Scripting
998ms
576ms
42.3%
Main thread time
8,225.2ms
7,450.0ms
9.4%
With fewer unnecessary re-renders, JavaScript execution time (scripting) and main thread load (main thread time) both went down.
Before memoizationAfter memoization
> You can see the render count drop by about 20 compared to without memoization. π
#### Memoizing the `getMasonryOptions` function
The getMasonryOptions function plays the key role of deciding each item's position and the layout options when implementing the Masonry layout.
The problem was that this function was being called inside the component every time the user scrolled (in other words, pointlessly often).
In a Masonry layout, most options stay the same unless the horizontal width changes.
But in the existing code, the getMasonryOptions function was called over and over whenever the scroll value (scrollY) changed, so layout calculations kept happening for no reason.
Since this function iterates over the entire array to calculate layout options, the computation cost grows significantly as the data grows.
For example, with 1,000 items, that meant 1,000 calculations repeated on every single scroll.
To improve this, I applied memoization.
```tsx title="Masonry.tsx"
const { masonryItems, masonryContainerHeight, columnWidth, centerOffset, policy } = useMemo(
() =>
getMasonryOptions({
containerWidth,
items,
listType,
isMobile,
viewport,
}),
[containerWidth, items, listType, isMobile, viewport],
);
```
Before memoizationAfter memoization
Now the unnecessary recalculation caused by vertical scroll state changes is gone completely. The function only runs when the options actually change, which prevents wasted computation.
### 4. Prefetching data with root margin
To implement the Masonry layout, I applied infinite scroll using `IntersectionObserver`.
Unlike a regular list, Masonry items stack in an irregular way.
Because of this, if you put the observer target element at the very bottom to detect the intersection, each column stacks to a different height, which leaves empty gaps.
To the user, this looks like the data is cut off, which can hurt the user experience.
To solve this, I used the `rootMargin` property to prefetch data and load it ahead of time.
I set rootMargin's bottom value high so that data is loaded in advance.
```ts
new IntersectionObserver(
(entries) => {
// ...μλ΅
},
{ rootMargin: '0px 0px 5000px 0px', threshold: 0.01 },
);
```
This way, when the user scrolls down, the data is already loaded, which prevents the cut-off effect.
Without rootMarginWith rootMargin
## Wrapping Up
Bringing a Masonry layout into the service myself was a continuous series of trial and error and deliberation, far more than I expected. I personally enjoy building UI and take pride in my UI implementation skills, but this Masonry layout was the most challenging and difficult task I've had.
I had to think from many angles, from complex policy design to varied data to performance issues, and I learned a lot of new things through the trial and error.
To respond effectively to different viewports and situations, going beyond a simple list, I kept trying various technical approaches,
and as a result I was able to achieve improvements on many fronts: performance optimization, a better user experience, and better memory efficiency.
In particular, the improvements were verified with actual numbers, which made the work all the more meaningful.
This journey of adopting Masonry was a valuable experience where I could directly feel its benefits, not only in UI/UX differentiation but also in the service's scalability and maintainability.
While developing, I was reminded once again that it's important not to stop at simply implementing features, but to think about improvements and act on them.
Above all, as a developer, I realized how important it is to keep caring about the code I write, and to keep finding improvements and growing the code, like watering a plant.
I also learned that it's right to optimize when there's a measurable performance problem, but that parts with a large structural impact should be considered at the initial design stage.