Make WordPress Core

Opened 9 days ago

Last modified 7 days ago

#48551 new enhancement

Twenty Twenty: Replace JS-based smooth scroll with CSS

Reported by: williampatton Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Bundled Theme Keywords: 2nd-opinion
Focuses: Cc:
PR Number:


The theme currently uses a JS based approach for smooth scroll. A CSS based approach was suggested as an alternative. Discussions were ongoing and there are pros and cons to each method.

Issue: https://github.com/WordPress/twentytwenty/issues/476
PR: https://github.com/WordPress/twentytwenty/pull/506

Details from the original ticket from GitHub:

Smooth scroll is currently implemented using a JS approach, that hijacks all anchors pointing to another location in the page, and replaces their default behaviour with a script that animates a page scroll. This is problematic for a number of reasons:

The animation is JS-based, blocking the main thread while executing and potentially leading to jank in slower devices (and some faster ones where JS-driven animations run at 60Hz while CSS-driven ones run at higher rates).
Being JS-based, the behaviour only takes place after the JS is fully loaded and executed, leading to inconsistencies in behaviour between the initial interactive page and the final one.
It hijacks regular anchors, which could interfere with screen readers and other assistive technologies.
It's a non-configurable behaviour that may be undesirable for certain categories of users that prefer less motion.
It's a non-standard behaviour that may interfere with how certain user agents display scrolling pages.
The current implementation is ~130 lines of complex JS (between smooth scroll, scrollToElement, and utility methods), that tries to take into account a number of things in the page to calculate the correct animation.

I propose instead using the standard scroll-behavior CSS property to obtain a similar effect. Switching to scroll-behavior would eliminate all the above issues, while reducing the implementation to a single line of CSS:

html {
  scroll-behavior: smooth;
This could be disabled for the purpose of other animations where the effect is not desirable (e.g. showing and closing modals) by adding/removing a single CSS class to the body:

.disable-smooth-scrolling {
  scroll-behavior: auto;
The downside of this approach is that it's not supported by all browsers, but given that this is a small visual improvement, I think it would fall squarely in the category of progressive enhancement, for which a standard behaviour fallback is acceptable, and preferable to the JS-based approach.

Change History (1)

#1 @ianbelanger
7 days ago

  • Keywords 2nd-opinion added
Note: See TracTickets for help on using tickets.