feat(#1932): implement smooth scrolling for anchor navigation across site #1965

Mohit5Upadhyay · 2025-07-07T10:55:01Z

Description

This PR implements smooth scrolling for in-page navigation across the Express.js website as mentioned in Issue : #1932

This improves the user experience by ensuring that navigation to sections via anchor links transitions smoothly, rather than jumping abruptly.

Closes #1932

Video

smooth-scrolling.mp4

…n across site

netlify · 2025-07-07T10:55:05Z

✅ Deploy Preview for expressjscom-preview ready!

Name	Link
🔨 Latest commit	`48aed9e`
🔍 Latest deploy log	https://app.netlify.com/projects/expressjscom-preview/deploys/688d6241df761200087c9ee6
😎 Deploy Preview	https://deploy-preview-1965--expressjscom-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

ShubhamOulkar · 2025-07-07T12:39:04Z

js/app.js

+  $(document).on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {
+    var href = $(this).attr('href');
+    if (smoothScrollToElement(href)) {
+      e.preventDefault();


Can you please remove this line https://github.com/expressjs/expressjs.com/blob/gh-pages/js/menu.js#L186 ? Since default behavior stopped here.

ShubhamOulkar · 2025-07-07T12:56:45Z

js/app.js

  });

+  // Smooth scrolling for all anchor links
+  $(document).on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {


Suggested change

$(document).on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {

$("#api-doc").on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {

We should minimize the scope of this click event. Currently, $(document).on('click'...) attaches the handler to all anchor links with # across every page. However, smooth scrolling is only needed on API pages, since the TOC exists only there. Scoping it to #api-doc avoids unnecessary event handling and prevents inconsistent anchor # behavior on other pages. Also, checking "#api-doc" exist on page is required before applying click event.

bjohansebas

Thanks for the PR!

As i mentioned in the issue, this can be handled through CSS, javascript is not necessary.

ShubhamOulkar · 2025-07-08T03:20:27Z

this can be handled through CSS,

I am OK with CSS only solution. But this approach comes with some limitations, like we cannot control scroll behavior and can not add header offsets. But it is fine if headings are not hiding behind the header bar on anchor link click.

Mohit5Upadhyay · 2025-07-08T09:25:27Z

Thanks @bjohansebas for the suggestion about a CSS-only solution!
Unfortunately, I think for this project, CSS alone isn’t sufficient because:

IDs like #app.METHOD (http://localhost:4000/en/5x/api.html#app.listen) contain dots, which CSS can’t reliably scroll to without custom JS.
We need a precise scroll offset (120px) to avoid headings hiding behind the navbar.

So I’d propose keeping the JS smooth scroll, scoped only to #api-doc to avoid global impact as per suggested by @ShubhamOulkar.

Let me know if you’d prefer another approach!
Thanks again for your feedback.

bjohansebas · 2025-07-11T18:45:50Z

But it is fine if headings are not hiding behind the header bar on anchor link click.

The headings are never hidden by the header bar, or at least I’ve been trying to reproduce it and haven’t been able to.

IDs like #app.METHOD (http://localhost:4000/en/5x/api.html#app.listen) contain dots, which CSS can’t reliably scroll to without custom JS.

That doesn’t matter in CSS, since the effect will be applied to all elements anyway.

* {
  scroll-behavior: smooth;
}

Mohit5Upadhyay · 2025-07-12T16:02:56Z

Hi @bjohansebas and @ShubhamOulkar,

I’ve updated the implementation to follow your suggestion of a CSS-only smooth scrolling solution.

I removed all the custom JavaScript smooth scroll code I previously added.
Instead, I’ve applied this in CSS:

* {
  scroll-behavior: smooth;
}

h1, h2, h3, h4, h5, h6,
[id] {
  scroll-margin-top: 120px;
}

@media (prefers-reduced-motion: reduce) {
  html {
    scroll-behavior: auto;
  }
}

Let me know if you’d like any further changes!
Thanks for your time! 🙏

bjohansebas · 2025-07-15T02:32:05Z

css/style.css

+h1, h2, h3, h4, h5, h6,
+[id] {
+  scroll-margin-top: 120px;
+}


I'm not sure if this is actually doing anything, and if it's supposed to have the same effect as in the MDN example https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top, then I'm -1 on this, I don't think we should do it.

without scroll top margin with scroll top margin

We can clearly see that margin spaces added to the header on scroll from the top of the viewport.
This property is used to increase visible area around the target element so that it is accessible to the user.

In our context, why it is important?
I expressed my concerns over the issue of hiding headers behind the top navigation bar in a comment above.

But it is fine if headings are not hiding behind the header bar on anchor link click.

This happens if top navigation is positioned sticky at the top. See image, express.raw() hide behind sticky top navigation.

It is not required right now, without scroll top margin, header scroll into viewport at top 0px. But I think adding some small margin 60px to the top looks good for me. Also our header is 57px height. Maybe I will go with sticky top navigation bar in #1943.

see scroll_padding_and_margin

ShubhamOulkar · 2025-07-15T06:00:32Z

css/style.css

+/* handle header offset with scroll-margin */
+h1, h2, h3, h4, h5, h6,
+[id] {
+  scroll-margin-top: 120px;


Suggested change

scroll-margin-top: 120px;

scroll-margin-top: 60px;

see comment https://github.com/expressjs/expressjs.com/pull/1965/files#r2206464995

ShubhamOulkar · 2025-07-15T06:10:14Z

css/style.css

  padding-top: 40px;
 }

-#api-doc *:target, #page-doc *:target {


I support removing this
since we are using scroll top margin only on headers.

css/style.css

ShubhamOulkar

Please do remove this line https://github.com/expressjs/expressjs.com/blob/gh-pages/js/menu.js#L186. On TOC main section heading click, it should scroll to main sections on the page. Currently, it is disabled. Only subsections get scrolled.

…reventDefault for TOC links

Mohit5Upadhyay · 2025-07-15T08:18:19Z

Hi @bjohansebas and @ShubhamOulkar,

Thanks so much for the thoughtful reviews!

Regarding scroll-margin-top:
I agree with @ShubhamOulkar that it’s helpful to prevent headings from hiding behind the sticky nav bar.

But I think adding some small margin 60px to the top looks good for me. Also our header is 57px height. Maybe I will go with sticky top navigation bar in #1943.

I’ll adjust the value to 60px as suggested, since our header height is ~57px.

Remove event.preventDefault() in menu.js so main TOC sections scroll as expected.

Let me know if there’s anything else you’d like tweaked!
Thanks again for your guidance.

ShubhamOulkar

I just tested, but default CSS scroll is too fast. On clicking main menu, the page scrolls really fast to that menu. Should we try putting some animation key frames to add some delays to scrolls?

Mohit5Upadhyay · 2025-07-19T13:42:09Z

hi @ShubhamOulkar,

Thank you for the suggestion regarding adding delays to scroll using animation keyframes.

I explored the possibility of controlling scroll speed using CSS keyframes alone. However, after testing locally, it turns out that CSS keyframes cannot manipulate scroll behavior that we need.

While scroll-behavior: smooth provides a basic smooth scroll effect, it doesn’t allow customization of speed or delay — and keyframes don’t apply to scroll position singly to achieve this.

To achieve the effect you’re suggesting (slower or delayed scrolling), we would need to implement a small JavaScript solution that programmatically controls the scroll animation.

Please let me know if you'd like me to proceed with a JavaScript-based implementation to match the desired behavior, or if you have any other suggestions — I’d be grateful to explore them!

Thanks!

bjohansebas · 2025-07-19T15:26:16Z

Please let me know if you'd like me to proceed with a JavaScript-based implementation to match the desired behavior, or if you have any other suggestions — I’d be grateful to explore them!

I’m -1 on implementing this in JavaScript. I want to simplify things as much as possible, and I don’t see it as reasonable to maintain that JavaScript when the platform itself already provides this solution (it might not be perfect, but it’s better than having to maintain JavaScript).

js/menu.js

…r submenu links Signed-off-by: Sebastian Beltran <[email protected]>

github-actions · 2025-08-02T00:56:27Z

🚦 Lighthouse Results (Mobile & Desktop)

URL	Device	Perf	A11y	Best Practices	⚠️ SEO score unreliable
/	mobile	🔴 66	🟢 100	🟢 96	🔴 63
/en/blog/posts.html	mobile	🔴 68	🟢 96	🟢 96	🔴 63
/en/5x/api.html	mobile	🔴 61	🟢 95	🟢 93	🔴 63
/	desktop	🟢 92	🟢 100	🟢 93	🔴 63
/en/blog/posts.html	desktop	🟢 94	🟢 96	🟢 96	🔴 63
/en/5x/api.html	desktop	🟢 92	🟢 95	🟢 100	🔴 63

github-actions · 2025-08-02T00:59:09Z

🚦 Lighthouse Results (Mobile & Desktop)

URL	Device	Perf	A11y	Best Practices	⚠️ SEO score unreliable
/	mobile	🔴 71	🟢 100	🟢 96	🔴 63
/en/blog/posts.html	mobile	🔴 63	🟢 96	🟢 93	🔴 63
/en/5x/api.html	mobile	🔴 62	🟢 95	🟢 96	🔴 63
/	desktop	🟢 94	🟢 100	🟢 96	🔴 63
/en/blog/posts.html	desktop	🟢 92	🟢 96	🟢 93	🔴 63
/en/5x/api.html	desktop	🟢 93	🟢 95	🟢 96	🔴 63

bjohansebas

LGTM

ShubhamOulkar

Need to remove line no 5 from app.js. Otherwise LGTM 👍

feat(expressjs#1932): implement smooth scrolling for anchor navigatio…

ee25a7b

…n across site

Mohit5Upadhyay requested a review from a team as a code owner July 7, 2025 10:55

ShubhamOulkar requested changes Jul 7, 2025

View reviewed changes

bjohansebas requested changes Jul 7, 2025

View reviewed changes

feat: implement CSS-only smooth scrolling for anchor navigation

736831c

bjohansebas reviewed Jul 15, 2025

View reviewed changes

ShubhamOulkar reviewed Jul 15, 2025

View reviewed changes

css/style.css Show resolved Hide resolved

ShubhamOulkar requested changes Jul 15, 2025

View reviewed changes

apply reviewer changes: Update scroll-margin-top to 60px and remove p…

9ce8ec4

…reventDefault for TOC links

ShubhamOulkar reviewed Jul 17, 2025

View reviewed changes

bjohansebas reviewed Jul 19, 2025

View reviewed changes

js/menu.js Show resolved Hide resolved

bjohansebas mentioned this pull request Jul 23, 2025

chore: ♻️ remove jquery #1964

Merged

4 tasks

bjohansebas added 2 commits August 1, 2025 19:51

Merge branch 'gh-pages' into feat-1932-smooth-scrolling

6daa170

remove scroll to top functionality and prevent default navigation fo…

48aed9e

…r submenu links Signed-off-by: Sebastian Beltran <[email protected]>

bjohansebas approved these changes Aug 2, 2025

View reviewed changes

bjohansebas requested a review from ShubhamOulkar August 2, 2025 00:59

ShubhamOulkar approved these changes Aug 2, 2025

View reviewed changes

bjohansebas added the design Change, update, or fix for site UI (not content) label Aug 2, 2025

bjohansebas merged commit de12edc into expressjs:gh-pages Aug 2, 2025
15 checks passed

	$(document).on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {
	$("#api-doc").on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {

Uh oh!

feat(#1932): implement smooth scrolling for anchor navigation across site #1965

feat(#1932): implement smooth scrolling for anchor navigation across site #1965

Uh oh!

Conversation

Mohit5Upadhyay commented Jul 7, 2025

Description

Video

Uh oh!

netlify bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for expressjscom-preview ready!

Uh oh!

ShubhamOulkar Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

ShubhamOulkar Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

bjohansebas left a comment

Choose a reason for hiding this comment

Uh oh!

ShubhamOulkar commented Jul 8, 2025

Uh oh!

Mohit5Upadhyay commented Jul 8, 2025

Uh oh!

bjohansebas commented Jul 11, 2025

Uh oh!

Mohit5Upadhyay commented Jul 12, 2025

Uh oh!

bjohansebas Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

ShubhamOulkar Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShubhamOulkar Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

ShubhamOulkar Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ShubhamOulkar left a comment

Choose a reason for hiding this comment

Uh oh!

Mohit5Upadhyay commented Jul 15, 2025

Uh oh!

ShubhamOulkar left a comment

Choose a reason for hiding this comment

Uh oh!

Mohit5Upadhyay commented Jul 19, 2025

Uh oh!

bjohansebas commented Jul 19, 2025

Uh oh!

Uh oh!

github-actions bot commented Aug 2, 2025

🚦 Lighthouse Results (Mobile & Desktop)

Uh oh!

github-actions bot commented Aug 2, 2025

🚦 Lighthouse Results (Mobile & Desktop)

Uh oh!

bjohansebas left a comment

Choose a reason for hiding this comment

Uh oh!

ShubhamOulkar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Jul 7, 2025 •

edited

Loading

ShubhamOulkar Jul 15, 2025 •

edited

Loading