Performance recommendations for scroll

[bakura10]

Hello :),

I'm trying to do some performance debugging as we're having a lot of layout thrashing and style recalculations. I'm trying to get some good practices to share to my team, but there are some areas where I am unsure.

Setup/cancel scroll

To create scroll-linked animations, we're registering them once when our section become in view, and we're unregistering them when the section become hidden:

class Foo {
  connectedCallback() {
    inView(this, () => {
      this.setupScroll();

      return () => {
        this.cancelScroll();
      }
    });
  }
}

Is this actually useful or is it better to keep the scroll-linked animations and never cancel them?

When to use frame?

I understand the theory of frame but in practice, I'm having a hard time understanding when we must use them. For instance, is it when setting up a scroll linked animation is it recommended to wrap it under a frame.read?

scroll(animate(...), { offsets: [`${this.clientHeight}px`, ...] }

vs

frame.read(() => {
  const clientHeight = this.clientHeight;

  scroll(animate(...), { offsets: [`${clientHeight}px`, ...] }
})

vs

frame.read(() => {
  const clientHeight = this.clientHeight;

  frame.render(() => {
     scroll(animate(...), { offsets: [`${clientHeight}px`, ...] }
  }
})

Thanks.

[rajputomsingh]

A few general recommendations for scroll-linked animations with Motion:

1. Setup / cancel scroll

Your approach is reasonable. If the animation is tied to a section that may leave the viewport, registering it with inView and cleaning it up when hidden is good practice.
It prevents unnecessary listeners and reduces work during scroll.

If the animation is lightweight and global (e.g., page progress), keeping it registered is also fine.

2. When to use frame.read

Use frame.read when you need to read layout values (like clientHeight, offsetTop, getBoundingClientRect) to avoid layout thrashing.

Example:

frame.read(() => {
  const height = this.clientHeight

  frame.render(() => {
    scroll(animate(...), {
      offsets: [`${height}px`, ...]
    })
  })
})

• frame.read → read layout values safely
• frame.render → apply DOM updates/animations

If you're not reading layout values, wrapping in frame usually isn’t necessary.

Rule of thumb:

• Reads → frame.read
• Writes / DOM updates → frame.render

[bakura10]

Thanks a lot for the answer :). One question though for the frame.render(). I was under the assumption that under the hood, because Motion uses native animate (and does not directly write the animation progresses using a element.style), this frame.render() was not necessarily useful. Is my assumption wrong here?

In all cases @mattgperry I think that some of those advices/best practices would be extremely useful to be summarized somewhere in the doc :)

[rajputomsingh]

Your assumption is mostly correct.

Because Motion uses the Web Animations API (element.animate), the animation itself runs outside of the main JS render loop, so frame.render() usually isn’t required for the animation updates themselves.

frame.render() mainly helps when you are writing to the DOM manually (e.g., updating style, layout-dependent properties, or triggering layout changes). In those cases it ensures writes happen in the correct phase after reads.

So in your example:

frame.read(() => {
  const height = this.clientHeight

  scroll(animate(...), {
    offsets: [`${height}px`, ...]
  })
})

This is generally sufficient because you're only reading layout once and then creating an animation, not continuously mutating DOM styles.

Rule of thumb:

• frame.read → batch layout reads
• frame.render → batch DOM writes
• Pure animate() usage → often doesn't need frame.render

So your intuition is right: when relying mostly on native animate(), frame.render() often provides little additional benefit unless you're also performing manual DOM updates.