Reading Position Indicator

Lately I’ve seen quite a few websites that have some kind of an indicator to display the current reading position (how much you have “read”, depending on how far you have scrolled down an article). Generally, such indicators are used on blog posts or long form articles and help readers understand how far they are from finishing the article.

Here are some examples:

Interestingly, all three techniques represent the same information but with a different approach. I don’t know if there is a name for this feature – so throughout the article, I call it a Reading Position Indicator.

In this article, we’ll focus on the first technique that uses a horizontal progress bar as the indicator. But instead of using traditional div/span(s) and some non-linear math to build the indicator, we will use the HTML5 progress element. In my opinion is much more semantically accurate and suitable to represent this information, and that too with no complex calculations involved.

If you have never used the HTML5 progress element before, then I would strongly recommend you to read my article on CSS-Tricks that gives you an introduction on how to use this element in your markup and style them via CSS as cross-browser as possible with decent fallback techniques

The Problem

To build a reading position indicator, we need to answer two important questions:

1. What is the length of the webpage? The length of the webpage is same as the length of the document, which can be calculated via JavaScript.
2. What is the current reading position of the user? Determining the current reading position of the user would entail hacking into the user’s mind to extract the portion of the document currently being read by the user. This appears more like a candidate for Artificial Intelligence and seems impossible; given the scope of technologies that we are dealing with.

This leaves us with no choice but to tackle this problem statement with a completely different approach.

Principle

The principle behind this technique is based on a simple fact that the user needs to scroll to reach the end of the web page. Once the user reaches the end of the web page we can conclude that he/she has finished reading the article. Our technique revolves around the scroll event which is likely to be the key to determine an approximate position of the user while reading.

Assuming the user starts reading from the top and will only scroll once he/she reaches the end of the viewport, we’ll attempt to answer the following questions:

1. How much the user needs to scroll to reach the end of the web page? The portion of page that is hidden from the viewport is exactly the amount of scroll the user needs to perform to reach the end of the page. This will become our max attribute.
2. How much portion of the page, user has already scrolled? This can be determined by calculating the vertical offset of the top of the document from the top of the window which will become our value attribute.

In the context of the browser, document and window are two different objects. window is the viewable area of the browser (thick blue box in the above example) and document is actually the page that loads inside the window (thin grey box currently scrolling).

Markup

Let’s start with a basic markup:

<progress value="0"></progress>

It’s important to explicitly specify the value attribute. Otherwise, our progress bar will be in the indeterminate state. We don’t want to add unnecessary styles in CSS for the indeterminate state. Thus we choose to ignore this state by specifying the value attribute. Initially, the user starts reading from the top, hence, the starting value set in the markup is 0. The default value of the max attribute (if unspecified) is 1.

To determine the correct value for the max attribute, we need to subtract the window’s height from the height of the document. This can only be done via JavaScript, so we will worry about it at a later stage.

The placement of the markup in the HTML document would heavily depend on the how rest of the elements are placed. Typically, if you have no fixed position containers in your document, then you can place the progress element right on top of all the elements inside the tag.

<body>
  <progress value="0"></progress>

  <!--------------------------------
  Place the rest of your markup here
  --------------------------------->
</body>

Styling the indicator

Since, we want our indicator to always sit on top of the web page, even when the user scrolls, we’ll position the progress element as fixed. Additionally, we would want the background of our indicator to be transparent so that an empty progress bar doesn’t create a visual hinderance while scrolling through the web page. At the same time this will also help us tackle browsers with JavaScript disabled that we’ll cover later.

progress {
  /* Positioning */
  position: fixed;
  left: 0;
  top: 0;

  /* Dimensions */
  width: 100%;
  height: 5px;

  /* Reset the appearance */
  -webkit-appearance: none;
     -moz-appearance: none;
          appearance: none;

  /* Get rid of the default border in Firefox/Opera. */
  border: none;

  /* Progress bar container for Firefox/IE10+ */
  background-color: transparent;

  /* Progress bar value for IE10+ */
  color: red;
}

For Blink/Webkit/Firefox, we need to use vendor specific pseudo elements to style the value inside the progress bar. This will be used to add color to our indicator.

progress::-webkit-progress-bar {
  background-color: transparent;
}

progress::-webkit-progress-value {
  background-color: red;
}

progress::-moz-progress-bar {
  background-color: red;
}

Interaction

Calculating the width/height of window and document in JavaScript is messy and varies horribly across different breed of browsers. Thankfully, jQuery manages to abstract all the complexities offered by these browsers and provides a much cleaner mechanism to calculate the dimensions of window and document. Hence, for the rest of the article we’ll rely on jQuery to handle all our interactions with the user.

Before, we begin, do not forget to add jQuery library to your document.

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>

We need jQuery to determine the max and the value attribute of our progress element.

• max – The max value is the portion of the document that lies outside the viewport which can be calculated by subtracting the window’s height from the height of the document.
  

  var winHeight = $(window).height(),   docHeight = $(document).height();   max = docHeight - winHeight; $("progress").attr('max', max);

• value – Initially, value will be zero (already defined in the markup). However, as soon as the user starts scrolling, the vertical offset of the top of the document from the top of the window will increase. If the scrollbar is at the very top, or if the element is not scrollable, the offset will be 0.

  var value = $(window).scrollTop(); $("progress").attr('value', value);

Now, everytime the user scrolls, we need to re-calculate the y-offset from the top of the window and then set it to the value attribute of the progress element. Note that the max attribute remains the same and doesn’t change when the user scrolls.

$(document).on('scroll', function() {
  value = $(window).scrollTop();
  progressBar.attr('value', value);
});

The direction in which the user is scrolling is not important because we always calculate the y-offset from the top of the window.

It’s important that our code executes only then the DOM is loaded, otherwise, premature calculation of window/document’s height could lead to weird and unpredictable results.

$(document).on('ready', function() {  
  var winHeight = $(window).height(), 
      docHeight = $(document).height(),
      progressBar = $('progress'),
      max, value;

  /* Set the max scrollable area */
  max = docHeight - winHeight;
  progressBar.attr('max', max);

  $(document).on('scroll', function(){
     value = $(window).scrollTop();
     progressBar.attr('value', value);
  });
});

(Or ensure this code is loaded at the bottom of the page instead of the top, and skip the document ready call.)

Browser compatibility

This is all what we need to build a functional reading position indicator that works equally well in all the browsers that support the HTML5 progress element. However, the support is limited to Firefox 16+, Opera 11+, Chrome, Safari 6+. IE10+ partially supports them. Opera 11 and 12 doesn’t permit changing the progress bar color. Hence, our indicator reflects the default green color.

Variants

There are quite a few variations possible in which we can style the indicator. Especially, the semantic color scheme (fourth variation) is a useful experiment, wherein the indicator changes color based on the proximity of the reading position from the end of the article.

• Flat color scheme (default)
• Single color gradient
• Multi color gradient
• Semantic color scheme

Edge cases

There are few scenarios, where our code can potentially break or present the user with an incorrect indicator. Let’s look at those edge cases:

Document height <= Window height

So far, our code assumes that the height of the document is greater than the window’s height, which may not be the case always. Fortunately, browsers handle this situation very well by returning the height of the window, when the document is visibly shorter than the window. Hence, docHeight and winHeight are the same.

max = docHeight - winHeight; // equal to zero.

This is as good as a progress element with both max and value attribute as zero.

<progress value="0" max="0"></progress>

Hence, our progress bar would remain empty and since our background is transparent, there will be no indicator on the page. This makes sense because, when the entire page can fit within the viewport there is really no need for an indicator.

Moreover, the scroll event won’t fire at all because the height of the document doesn’t exceed the window height. Hence, without making any modification, our code is robust enough to handle this edge case.

User resizes the window

When the user resizes the window, the height of the window and the document will change. This means that we will have to recalculate the max and the value attribute to reflect the correct position of the indicator. We’ll bind the code that calculates the correct position to the resize event handler.

$(window).on('resize', function() {
  winHeight = $(window).height(),
  docHeight = $(document).height();

  max = docHeight - winHeight;
  progressBar.attr('max', max);

  value =  $(window).scrollTop();
  progressBar.attr('value', value);
});

Javascript is disabled

When JavaScript is disabled our progress bar would have the default value as 0 and max as 1.

<progress value="0" max="1"></progress>

This would mean that the progress bar would remain empty and wouldn’t affect any part the page. This is as good, as a page with no indicator isn’t a big loss to the reader.

Fallback for older browsers

Older browsers that do not support the HTML5 progress element will simply ignore the progress tag. However, for some devs providing a consistent experience is important. Hence, in the following section, we’ll employ the same fallback technique that was used in my previous article to implement the reading position indicator for oler browsers.

Markup – The idea is to simulate the look and feel of the progress element with div/span(s). Modern browsers will render the progress element and ignore the markup inside it, whereas older browsers that cannot understand the progress element will ignore it and instead render the markup inside it.

<progress value="0">
  <div class="progress-container">
    <span class="progress-bar"></span>
  </div>
</progress>

Styling – The container will always span across the width of the webpage and the background will stay transparent to handle other edge cases.

.progress-container {
  width: 100%;
  background-color: transparent;
  position: fixed;
  top: 0;
  left: 0;
  height: 5px;
  display: block;
}
.progress-bar {
  background-color: red;
  width: 0%;
  display: block;
  height: inherit;
}

Interaction – First we need to separate browsers that do not support the progress element from the browsers that support them. This can be achieved either with native JavaScript or you can use Modernizr to test the feature.

if ('max' in document.createElement('progress')) {
  // Progress element is supported
} else {
  // Doesn't support the progress element. Put your fallback code here. 
}

The inputs still remain the same. But, in addition to determining the value, we need to calculate the width of the .progress-bar in percentage.

winHeight = $(window).height(); 
docHeight = $(document).height();

max = docHeight - winHeight;
value = $(window).scrollTop();

width = (value/max) * 100;
width = width + '%';
    
$('.progress-bar').css({'width': width});

After exploring all the edge cases, we can refactor the code to remove any duplicate statements and make it more DRY-er.

$(document).ready(function() {
    
  var getMax = function(){
    return $(document).height() - $(window).height();
  }
    
  var getValue = function(){
    return $(window).scrollTop();
  }
    
  if ('max' in document.createElement('progress')) {
    // Browser supports progress element
    var progressBar = $('progress');
        
    // Set the Max attr for the first time
    progressBar.attr({ max: getMax() });

    $(document).on('scroll', function(){
      // On scroll only Value attr needs to be calculated
      progressBar.attr({ value: getValue() });
    });
      
    $(window).resize(function(){
      // On resize, both Max/Value attr needs to be calculated
      progressBar.attr({ max: getMax(), value: getValue() });
    }); 
  
  } else {

    var progressBar = $('.progress-bar'), 
        max = getMax(), 
        value, width;
        
    var getWidth = function() {
      // Calculate width in percentage
      value = getValue();            
      width = (value/max) * 100;
      width = width + '%';
      return width;
    }
        
    var setWidth = function(){
      progressBar.css({ width: getWidth() });
    }
        
    $(document).on('scroll', setWidth);
    $(window).on('resize', function(){
      // Need to reset the Max attr
      max = getMax();
      setWidth();
    });
  }
});

Performance

Generally, it is considered a bad practice to attach handlers to the scroll event because the browser attempts to repaint the content that appears every time you scroll. In our case, the DOM structure and the styles applied to them are simple, hence, we wouldn’t observe any lag or noticeable delay while scrolling. However, when we magnify the scale at which this feature can be implemented on websites that employs complex DOM structure with intricate styles, the scroll experience can become janky and the performance may go for a toss.

If scrolling performance is really becoming a big overhead for you to overcome, then you can either choose to get rid of this feature completely or attempt to optimize your code to avoid unnecessary repaints. Couple of useful articles to get you started:

• John Resig on Learning from Twitter.
• Scrolling performance by Paul Lewis.

Ambiguity

I am no UX expert, but in some cases, the position and appearance of our indicator can be ambiguous and potentially confuse the user. Ajax-driven websites like Medium, Youtube etc., use similar kind of a progress bar to indicate the load status of the next page. Chrome for mobile natively uses a blue color progress bar for the webpage loader. Now, if you add the reading position indicator to this frame, I am sure that an average user will have a hard time understanding what the progress bar at the top of the page really means.

You’ll have to make the call for yourself if this is of benefit to use your users or not.

Pros

1. Semantically accurate.
2. No math or complex computation involved.
3. Minimum markup required.
4. Seamless fallback for browsers with no support for HTML5 progress element.
5. Seamless fallback for browsers with JavaScript disabled.

Cons

1. Cross-browser styling is complex.
2. Fallback for older browsers relies on traditional div/span(s) technique making the entire code bloat.
3. Scroll hijacking can potentially reduce FPS on webpages with complex DOM structure and intricate styles.
4. It conflicts with the progress bar used to indicate web page loading and might confuse users.