The rendering pipeline

From DOM to pixels

Your page is a tree of elements, called the DOM, plus CSS rules. The screen shows pixels: tiny colored dots. A browser can't draw an element straight from the DOM. It goes through a few steps first:

1. It works out which CSS values apply to each element.
2. It measures each box and decides where it goes.
3. It draws the pixels.
4. It puts the drawn parts together on the screen.

The stages always come in this order. But not every change runs every stage. A new text color doesn't move a box, so the browser doesn't need to measure again. A new width can move many boxes. So the property you change decides how much work the browser must do.

This lesson follows From HTML to running script. That lesson shows how the page and its scripts arrive. This lesson starts after that, when JavaScript or the user changes the page and the browser must draw it again.

Style, layout, paint, and composite

Style (short for style calculation) finds the final CSS value of each property for each element. It mixes together:

• the browser's own default styles,
• your CSS rules,
• values an element gets from its parent (called inherited values),
• inline styles, set right on the element.

The result is one value for each property, such as a color, a width, or a transform.

Layout measures each box and decides where it goes. It answers questions like these:

• How wide is this card?
• Where does its text wrap onto a new line?
• Where does the next card start?

Many performance tools call layout reflow. Both words mean the same thing.

1const box = document.createElement("div");2box.style.width = "120px";3document.body.append(box);4console.log(box.offsetWidth);

Line 1 creates a new div box. Line 2 sets its width to 120px. Line 3 adds it to the page. Line 4 reads offsetWidth, the box's measured width in pixels, and prints 120. So the CSS value you wrote became a real measured size.

Paint draws the pixels for everything you can see: text, backgrounds, borders, shadows, and images.

Composite (short for compositing) takes the painted parts and puts them together on the screen, in the right order. It also cuts off parts that should be hidden. And it applies two effects you'll meet again in this lesson:

• transform: moves, turns, or resizes an element on the screen.
• opacity: how see-through an element is, from 0 (invisible) to 1 (solid).

These four names are a simple overview. Real browsers split the work into more steps. For example, Chrome has a step called raster, which turns paint's drawing instructions into pixels. A browser also skips the stages it doesn't need. During some animations, it skips layout and paint completely.

Forced layout: reading right after a change

Browsers like to wait before they do rendering work. That way, they can handle many changes in one go. When you change a style, the browser only makes a note: "layout must run again". This is called marking layout dirty. Then it waits for the next frame, the next picture it draws on the screen, and measures everything once.

A forced synchronous layout happens when JavaScript changes something and then asks for a size or a position straight away. "Synchronous" means right now, before your next line of code runs. The browser can't wait for the next frame, because your code needs the answer now. These reads need an up-to-date answer:

• offsetWidth: the element's measured width.
• getBoundingClientRect(): the element's size and position on the screen.
• some values from getComputedStyle(), which gives the final CSS values.

1const box = document.createElement("div");2box.style.width = "120px";3document.body.append(box);4console.log(box.offsetWidth); // 120

Line 1 creates the box. Line 2 sets its width to 120px. Line 3 adds the box to the page. Line 4 asks for the width right now. So the browser runs layout first, and then gives back 120.

This is not always a bug. Some code really needs the current size. For example, a drag handle, a tooltip, or code that places a menu next to a button. It only becomes a problem when your code makes the browser do this work many times in one update.

1const box = document.createElement("div");Run2box.style.width = "120px";3document.body.append(box);4const width = box.offsetWidth;5console.log(width);

Read first, then write

Layout thrashing is a pattern you can avoid. Your code does these steps again and again:

1. Write a style, for example a new width.
2. Read a size, for example offsetWidth.
3. Write another style.
4. Read another size.

Each read can force the browser to run layout before your code can go on. "Thrashing" means the browser keeps doing the same work over and over.

1const cards = [...document.querySelectorAll(".card")];2for (const card of cards) {3  card.style.width = `${card.offsetWidth + 10}px`;4}

Line 1 collects all the cards into an array. Line 2 starts a loop over the cards. Line 3 reads the card's offsetWidth and writes a new width, 10 pixels wider, in the same line. On the next turn of the loop, the read comes straight after the last write. So the browser may have to run layout again for every card. The exact work depends on the browser, but this pattern makes extra work you don't need.

1const cards = [...document.querySelectorAll(".card")];2const widths = cards.map((card) => card.offsetWidth);3for (const [index, card] of cards.entries()) {4  card.style.width = `${widths[index] + 10}px`;5}

Line 2 reads every old width into an array called widths, before any width changes. Lines 3 and 4 then write all the new widths together. cards.entries() gives each card with its position number, index, so line 4 can find that card's old width. Now the browser can usually handle all the writes in one layout at the next frame.

The step-through below uses a small model of this. It counts how many times layout must run:

• A write marks layout dirty.
• A read, or the next frame, runs layout only if it is dirty. Then layout is clean again.

1const first = countLayouts(["write", "read", "write", "read"]);Run2const second = countLayouts(["read", "read", "write", "write", "frame"]);3console.log(first);4console.log(second);

1const first = countLayouts(["write", "read", "write", "read"]);2const second = countLayouts(["read", "read", "write", "write", "frame"]);3console.log(first);4console.log(second);

Layers and compositing

A layer is a separate painted sheet that the browser can put on the screen on its own. The browser may give an element, or part of the page, its own layer. Then the compositor, the part of the browser that does the composite stage, can move, cut, or fade that sheet. It doesn't have to run layout or paint again.

For example, the browser may put an element that moves with transform on its own layer. The CSS property will-change: transform tells the browser, "this element will probably move soon". Starting a transform animation can also make the browser prepare a layer.

1.card {2  will-change: transform;3}

Line 1 picks every element with the class card. Line 2 gives the browser a hint: the transform will probably change. Line 3 closes the rule. This hint doesn't promise a layer. It doesn't make every animation fast either. It only gives the browser information it may use.

Too many layers waste memory, because the browser must store every sheet. They can also add extra composite work. So add the hint only where you measured a real problem. Remove it when the element no longer moves.

Which changes make the browser redo layout or paint

The property you change gives a good first guess about the work. A new width, height, top, or font can change sizes and positions. So the browser usually needs all four stages: style, layout, paint, and composite.

Two more words you'll see in tools: reflow is another name for layout, and repaint means running paint again.

1const changes = [2  ["width", "layout, paint, composite"],3  ["background-color", "paint, composite"],4  ["transform", "often composite only"],5];6console.log(changes.map(([property, work]) => `${property}: ${work}`).join(" | "));

Line 1 starts an array of pairs. Each pair is a property name and the work it usually needs. Lines 2 to 4 hold the three pairs. Line 6 joins the pairs into one line, with | between them, and prints width: layout, paint, composite | background-color: paint, composite | transform: often composite only.

Each row of the table below is one kind of change. Read across to see which stages it usually needs, and why.

A new color or background-color usually keeps every box the same size. But the pixels change, so the browser must paint again. In most browsers, transform and opacity can often skip layout and paint, and run only in the composite stage. But some things can add work back:

• filters, such as a blur,
• blending colors with what is behind the element,
• parts that are cut off (clipped),
• the elements inside it,
• the browser's own choices.

Animation off the main thread

The main thread is the part of the browser that does one job at a time for your page. It runs your JavaScript, your event handlers, most of style and layout, and other page work. The compositor works on its own, separately. So it can often keep a ready transform or opacity animation moving, even while the main thread is busy with JavaScript.

That is why these tools are a good fit for moving and fading things, when they animate transform or opacity:

• CSS transitions,
• CSS animations,
• the Web Animations API, which lets JavaScript start an animation with element.animate().

This is a chance for smoother motion, not a promise. Keep the animated content simple. Then check a performance trace: a recording of everything the browser did, made with the browser's developer tools.

1const box = document.createElement("div");2box.style.width = "40px";3box.style.height = "40px";4document.body.append(box);5box.animate(6  [{ transform: "translateX(0px)", opacity: 1 }, { transform: "translateX(80px)", opacity: 0.5 }],7  { duration: 300, fill: "forwards" },8);9console.log("animation started");

Lines 1 to 4 create a 40-pixel square box and add it to the page. Lines 5 to 8 start an animation. box.animate() takes two things:

• a list of keyframes: how the box looks at the start and at the end,
• the timing: here, 300 milliseconds.

The box slides 80 pixels to the right and fades to half see-through. fill: "forwards" keeps the end look after the animation finishes. Line 9 prints animation started. It only shows that the animation started. It doesn't measure how smooth it was.

For moving things on everyday pages, see animation. For changing CSS from JavaScript, see styles and classes and sizes and coordinates.

Checking it in a real browser

Here is one fact you can see for yourself. When a page sets a width and then reads the size, the read gives back the new width. This doesn't show how the browser works inside. But it proves that JavaScript gets the current size when it asks.

1const box = document.createElement("div");2box.style.width = "120px";3document.body.append(box);4console.log(box.offsetWidth);5console.log(getComputedStyle(box).width);

Line 1 makes a box. Line 2 sets its width. Line 3 adds it to the page. Line 4 prints 120, the measured width. Line 5 prints 120px, the final CSS width from getComputedStyle(). The lesson's test runs this code in Chrome when Chrome can start, and skips this check when it can't.

1const box = document.createElement("div");2box.style.width = "120px";3document.body.append(box);4console.log(getComputedStyle(box).width);

This code is the same, except line 4 asks getComputedStyle() for the width. It prints 120px: a string that includes the unit.

Don't use this to claim how fast something is. How long rendering takes depends on the device, the page, and when the next frame comes. The only safe claim is that the read shows the new style.

Good habits for fast rendering

Start with the problem you can see. If typing, dragging, or scrolling feels jumpy, record a performance trace before you change any properties. In the trace, look for:

• long JavaScript tasks,
• style, layout, paint, or composite work that repeats around the moment you typed, dragged, or scrolled.

Then remove work you don't need. Keep DOM changes small. Read sizes before you write new sizes. Use transform or opacity for motion when that gives the look you want. Treat each of these as an idea to test, not a rule to follow without checking.

• Read all the layout values first. Then write the styles that change layout.
• Use transform to move things and opacity to fade them, when the result looks right.
• Use will-change only for a problem you measured, and only for a short time. Don't put it everywhere.
• Check the browser's trace. Don't guess from one property name alone.

This lesson connects to rendering performance, which uses these ideas to make everyday pages faster. It also connects to rendering and the event loop, which explains when the browser gets a chance to paint.

Common misconceptions

• “Every DOM change lays out the whole page straight away.” Browsers often wait until a value is needed, or until the next frame.
• “Reading a size is always bad.” Sometimes you really need the current size. The problem is a loop that reads straight after each write.
• “will-change makes anything fast.” It is a hint that costs memory. It is not a switch that makes things fast forever.
• “Transform is always free.” It can often skip layout and paint. But big layers and visual effects still cost work.
• “Off the main thread means JavaScript doesn't matter.” An animation in the compositor may keep going. But long JavaScript tasks still make clicks and typing slow, and they delay other page work.

Each row of the table below is one word from this lesson. Read across to see what it means and what it is easy to mix it up with.

Practice exercises

const box = document.createElement("div");
box.style.width = "75px";
document.body.append(box);
console.log(box.offsetWidth);

function countLayouts(steps) {
  let dirty = false;
  let layouts = 0;
  for (const step of steps) {
    if (step === "write") dirty = true;
    if ((step === "read" || step === "frame") && dirty) {
      layouts += 1;
      dirty = false;
    }
  }
  return layouts;
}
console.log(countLayouts(["write", "read", "write", "read"]));

panel.style.transform = "translateX(0)";

Check your understanding

Use the stage names carefully. Keep a rule of thumb apart from a result you measured on a real page.

Key takeaways

• Style finds the CSS values. Layout measures the boxes. Paint draws the pixels. Composite puts the painted parts together.
• Reading a size straight after a style change can force the browser to run layout right now.
• Read all sizes first, then write. This stops layout from running again and again in one update.
• Layers can make composite work cheaper, but too many layers use a lot of memory.
• In most browsers, transform and opacity can often animate smoothly in the composite stage alone.
• Measure a real interaction before you choose a fix.

Coming next: How input reaches your event handlers. You'll follow a click, a touch, or a key press from the moment the browser finds which element was hit to the JavaScript listener that runs.