Adding a Back to Top Feature to the Website

The Hugo Clarity skin used on this site comes with a built-in back-to-top feature. I wasn't satisfied with the icon, so I changed it to its current form for easier identification. The "Back to Home" icon is always visible, which is a bit annoying. So, we need to optimize it so that it's not displayed by default. Only when the scrollbar scrolls down a certain distance, exceeding this threshold, will the "Back to Top" icon appear. Beyond that, it will be hidden.

The implementation logic is simple and easy to understand. The entire change is shown in the image below:

hugo back to top

The changes are explained below.

1. Add an id to the element containing the icon

Adding an id is to facilitate subsequent operations and control whether the icon is displayed. The changes are as follows:

 1diff --git a/layouts/partials/top.html b/layouts/partials/top.html
 2index bdaa538..33aade0 100644
 3--- a/layouts/partials/top.html
 4+++ b/layouts/partials/top.html
 5@@ -1,3 +1,3 @@
 6-<a class="to_top" id="toTop" href="#documentTop">
 7- <img src="/icons/to-top.svg" width="44" height="44" alt="to-top" />
 8-</a>
 9+<a class="to_top" href="#documentTop">
10+ <img src="/icons/to-top.svg" width="44" height="44" alt="to-top">
11+</a>
12\No newline at end of file

The difference is that the tag has an id="toTop" added to it.

2. Setting the default hidden icon

 1diff --git a/assets/sass/_components.sass b/assets/sass/_components.sass
 2index 8a2c398..301844a 100644
 3--- a/assets/sass/_components.sass
 4+++ b/assets/sass/_components.sass
 5@@ -546,7 +546,6 @@ figcaption
 6
 7.to
 8&_top
 9- visibility: hidden
10background-color: transparent
11width: 2.75rem
12height: 2.75rem
13(END)

The visibility: to_top property has been added. hidden means hidden by default. The element is still there. This improves performance (it doesn't need to be frequently created/deleted during scrolling), but it still affects the layout.

3. Add control logic

 1diff --git a/assets/js/custom.js b/assets/js/custom.js
 2index 54f7fe3..11b1d82 100644
 3--- a/assets/js/custom.js
 4+++ b/assets/js/custom.js
 5@@ -1,11 +1 @@
 6-// add custom js in this file
 7-
 8-window.onscroll = function () {
 9- var pageOffset =
10- document.documentElement.scrollTop || document.body.scrollTop;
11- if (pageOffset > 1000) {
12- document.getElementById("toTop").style.visibility = "visible";
13- } else {
14- document.getElementById("toTop").style.visibility = "hidden";
15- }
16-};
17+// add Custom JS in this file
18\ No newline at end of file
19(END)

The custom JS code for this skin is placed in custom.js and is originally empty. The code above executes the function inside during scrolling. If the vertical offset from the top (how much is hidden due to scrolling) is greater than 1000 pixels, the element with the id toTop is made visible; otherwise, it is hidden. The effect is that the icon appears when scrolling down a certain distance, and disappears when scrolling down a certain distance.

Explanation of scrollTop in English:

An element's scrollTop value is a measurement of the distance from the element's top to its topmost visible content. When an element's content does not generate a vertical scrollbar, its scrollTop value is 0.

If you still don't understand, see this stackoverflow answer.

scrollTop cat

Finally, since the page anchor "documentTop" is above the body element, clicking it will return to the top. Readers can scroll through the site to see how this works. Of course, every website's code structure is different. Once you understand the principles, you can add this functionality yourself. I'm not a front-end professional, so this implementation isn't necessarily the best practice, but it works for me, and I'm sharing it for non-professionals to use as a reference.

Lastmod: Wednesday, July 30, 2025

See Also:

Translations: