How to add a scroll-based progress bar to your Ghost CMS site

Adding a scroll-based progress bar to your Ghost CMS site can greatly enhance the user experience. In this step-by-step tutorial, we will guide you through the process of creating a customizable scroll-based progress bar using HTML plain JavaScript and CSS.

We will do this from the Ghost CMS Admin, no need to edit theme files, everything can be done from Ghost Code Injection and will work no matter what theme you are using.

Let's explore how we can do this, starting with the HTML markup.

The Progress indicator element

The <progress> HTML element is a built-in tool for displaying the progress of a task or process. It allows you to visually represent the completion status using a progress bar. This is perfect for our purposes.

The <progress> element supports two essential attributes:

• value: This attribute sets the current value of the progress bar. It represents the completion percentage and can range from 0 to the value specified in the max attribute.
• max: This attribute defines the maximum value that the value attribute can reach. It represents 100% completion and determines the length of the progress bar.

Here's how our element will look like:

<progress class="progress-bar" value="0" max="100"></progress>

Style the progress indicator

The next step is creating the necessary CSS styles to define the appearance of the progress bar. Here's the minimum styling needed for the element:

.progress-bar {
    appearance: none;
    position: fixed;
    top: 0;
    width: 100%;
    height: 5px;
    background: transparent;
    z-index: 1000;
}

.progress-bar::-webkit-progress-bar { background: transparent; }
.progress-bar::-moz-progress-bar { background: var(--ghost-accent-color); }
.progress-bar::-webkit-progress-value { background: var(--ghost-accent-color); }

In the code above, we define the .progress-bar class to style our progress bar element. Adjust the CSS properties according to the desired appearance and layout of your Ghost CMS site.

The progress bar color will be based on --ghost-accent-color, which is your brand color defined in the Designs settings.

Track the scroll progress

To bring the scroll-based progress bar to life we need to track the scroll event. For this we need JavaScript. Here's the necessary code:

const progressBar = document.querySelector('.progress-bar');

if (progressBar) {
  progressBar.setAttribute('value', getScrollPercent());  
  window.addEventListener('scroll', (event) => {
    progressBar.setAttribute('value', getScrollPercent());
  }, false);
}
    
function getScrollPercent() {
  const h = document.documentElement, 
        b = document.body,
        st = 'scrollTop',
        sh = 'scrollHeight';
  return Math.round((h[st]||b[st]) / ((h[sh]||b[sh]) - h.clientHeight) * 100);
}

The above code is responsible for handling the updates to the progress bar as the user scrolls through the page.

The getScrollPercent() function calculates the scroll percentage based on the current scroll position and the total height of the page. It returns the scroll percentage as a rounded integer value.

To ensure the progress bar updates dynamically, the scroll event listener is attached to the window object. As the user scrolls, the progress bar's value attribute is updated using the getScrollPercent() function.

Integrate the code in Ghost

At this point we have all we need to implement the feature, we just have to take everything and put it together.

Add the following in your Settings > Code injection header:

<style>
  .progress-bar {
    appearance: none;
    position: fixed;
    top: 0;
    width: 100%;
    height: 5px;
    background: transparent;
    z-index: 1000;
  }

  .progress-bar::-webkit-progress-bar { background: transparent; }
  .progress-bar::-moz-progress-bar { background: var(--ghost-accent-color); }
  .progress-bar::-webkit-progress-value { background: var(--ghost-accent-color); }
</style>

Add the following in your Settings > Code injection footer:

<progress class="progress-bar" value="0" max="100"></progress>
<script>
  const progressBar = document.querySelector('.progress-bar');

  if (progressBar) {
    progressBar.setAttribute('value', getScrollPercent());  
    window.addEventListener('scroll', (event) => {
      progressBar.setAttribute('value', getScrollPercent());
    }, false);
  }
      
  function getScrollPercent() {
    const h = document.documentElement, 
          b = document.body,
          st = 'scrollTop',
          sh = 'scrollHeight';
    return Math.round((h[st]||b[st]) / ((h[sh]||b[sh]) - h.clientHeight) * 100);
  }
</script>

At this point, you have successfully integrated a scroll-based progress bar into your Ghost CMS site.

However, you may want to further customize its appearance to align with your theme's design. Feel free to modify the CSS styles or add additional styling to the .progress-bar class. You can adjust the position, size, and colors of the progress bar by tweaking the corresponding CSS properties within the existing styles.

Additionally, you can make the progress bar appear only on posts, by adding the following in your Settings > Code injection header:

<style>
.progress-bar { display: none; }
.post-template .progress-bar { display: block; }
</style>

Conclusion

By following this comprehensive guide, you have learned how to effortlessly incorporate a scroll-based progress bar into your Ghost CMS site. You can fully personalize the appearance and functionality of the progress bar.

By providing visual feedback on the user's progress, you enhance the user experience and keep your audience engaged.