Skip to content

Lesson 40 ยท JavaScript and Interactivity

Skeleton Loaders, Scrollspy and Sticky Navigation

Build skeleton loaders with Bootstrap placeholders and swap in real content, then create a docs layout with a sticky sidebar and ScrollSpy.

Two small touches make a page feel polished. The first is how it behaves while waiting: a blank gap feels broken, while a gray outline of the content to come feels fast. The second is how it helps people find their way through a long page: a sidebar that stays in view and highlights the section being read.

Bootstrap supports both. Placeholders draw skeleton loading shapes, and ScrollSpy with sticky positioning builds the table-of-contents sidebar used by documentation sites. You met the basic syntax in Alerts, Badges, Progress and Spinners and Plugin Events and Programmatic Control. This lesson goes further with complete patterns: swapping skeletons for real data, accessible loading states, and a sticky ScrollSpy layout with smooth scrolling, offsets and nested links.

Placeholders: a quick recap

A placeholder is a gray block drawn by adding placeholder to an inline element. Its width comes from the grid column classes (col-6), and its height from the text size around it.

Class Effect
placeholder The gray block
placeholder-lg, placeholder-sm, placeholder-xs Height of the block
placeholder-glow (on the parent) Fades the blocks in and out
placeholder-wave (on the parent) A moving highlight sweeps across
bg-* Color the block (for example bg-primary)

The skeleton should resemble the final layout: same number of lines, similar widths, same image box. When the real content arrives, nothing should jump.

Swapping a skeleton for real content

A skeleton is only useful if it goes away. The pattern is: render the skeleton in the HTML, fetch the data, and replace the skeleton's markup. In the example below, a timer plays the part of a network request.

Skeleton card that loads

Notes on the markup:

  • The skeleton shapes are wrapped in aria-hidden="true": empty gray blocks mean nothing to a screen reader. A visually-hidden message ("Loading article") tells assistive technology what is going on.
  • The card carries aria-live="polite" and aria-busy. While busy is true the region's changes are held back, and when it flips to false the new content is announced politely.
  • The skeleton's layout (an 8rem image area, three text lines, a button-shaped block) matches the final card, so the card does not change height when the data arrives.
  • A disabled link that is only there as a button shape uses disabled and aria-disabled="true". Do not make a placeholder button focusable.

When to use a skeleton instead of a spinner

  • Use a skeleton when you know the shape of the result and the wait is short to medium (lists, cards, article pages). It sets expectations and reduces perceived waiting time.
  • Use a spinner when the layout is unknown, the action is a button press (a small spinner inside the button) or the wait is indeterminate.
  • Use neither for fast operations: flashing a skeleton for 100 ms looks worse than nothing. Start showing it only if the response takes longer than about 200-300 ms.
  • With prefers-reduced-motion, Bootstrap automatically turns off the glow and wave animations.

ScrollSpy and sticky navigation

ScrollSpy highlights the navigation link of the section currently in view. Combined with a sticky sidebar, it forms the classic documentation layout: a long article on the right, a table of contents that follows you on the left.

The three ingredients

  1. A navigation made of links to section ids (<a href="#intro">), such as a list-group, a nav or a navbar.
  2. A scroll area: the <body> or a scrollable box marked with data-bs-spy="scroll" and data-bs-target="#the-nav". Each section needs the id that a link points to.
  3. A way to keep the nav visible: Bootstrap's sticky-top class (or position-sticky with a top offset) on the nav's wrapper.

The attributes you can add to the scroll area:

Attribute Purpose
data-bs-spy="scroll" Enables ScrollSpy
data-bs-target="#nav" The navigation to update
data-bs-smooth-scroll="true" Smooth scrolling when a link is clicked
data-bs-root-margin="0px 0px -40%" Which band of the viewport counts as "current" (default 0px 0px -25%)
data-bs-threshold="0.1,0.5,1" Visibility ratios that trigger updates
tabindex="0" Lets keyboard users scroll a box

Because ScrollSpy uses an IntersectionObserver, the root margin works like the one you met in Intersection, Resize and Mutation Observers. A margin of -40% at the bottom means a section becomes active when it enters the upper 60% of the scroll area.

A documentation layout

The demo uses a scrollable box to keep the example self-contained. On a real page, put the attributes on <body> and let the page itself scroll.

Sticky sidebar with ScrollSpy

What to notice:

  • Nested navs. The nested nav inside the parent keeps its children indented, and Bootstrap marks both the child link and its parent link active while a child section is in view.
  • data-bs-root-margin="0px 0px -50%". Only the upper half of the box counts, so a section is "current" while it is in the top half, which matches how people read.
  • Smooth scrolling. data-bs-smooth-scroll="true" scrolls smoothly on link clicks, and the CSS scroll-behavior: smooth helps for a box. Respect prefers-reduced-motion on your own pages by only enabling it when the user has not asked for less motion.
  • Space after the last section. A final section shorter than the scroll area can never reach the "active" band at the very bottom. Extra bottom padding fixes it.
  • The event. activate.bs.scrollspy fires on the navigation with event.relatedTarget set to the newly active link.

Making the sidebar sticky on a real page

On a full page, the markup is the same but the attributes go on body, and the sidebar is pinned with sticky-top:

HTML
<body data-bs-spy="scroll" data-bs-target="#toc" data-bs-root-margin="0px 0px -40%" tabindex="0">
  <header class="navbar sticky-top bg-body-tertiary">...</header>

  <div class="container">
    <div class="row">
      <aside class="col-md-3">
        <nav id="toc" class="sticky-top nav flex-column" style="top: 4.5rem" aria-label="On this page">
          <a class="nav-link" href="#intro">Intro</a>
          ...
        </nav>
      </aside>
      <main class="col-md-9">
        <section id="intro" class="scroll-margin">...</section>
      </main>
    </div>
  </div>
</body>

Two details matter with a sticky header:

  1. Give the sticky sidebar a top offset that equals the header height (top: 4.5rem above), or it hides under the header.
  2. When a link scrolls to a section, the heading would be hidden behind the header. Fix it with the CSS property scroll-margin-top on the targets:
CSS
main section { scroll-margin-top: 5rem; }

On small screens, hide the sidebar or move it into a collapsed block (d-none d-md-block), because a sticky sidebar eats screen space.

Creating and refreshing from JavaScript

If you build the page dynamically, create the plugin yourself and refresh it after the DOM changes:

JavaScript
const spy = new bootstrap.ScrollSpy(document.body, {
  target: "#toc",
  rootMargin: "0px 0px -40%",
  smoothScroll: true,
});

// after adding or removing sections:
spy.refresh();

Accessibility notes

  • Give the navigation an aria-label such as "On this page", so screen reader users can tell it apart from the main menu.
  • Highlighting is a visual cue only. Keep real links so everything works without ScrollSpy.
  • Never rely on color alone to show the active link. The demo adds a border and bolder text.
  • A scrollable box must be focusable (tabindex="0") so keyboard users can scroll it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why wrap placeholder shapes in aria-hidden="true" and add a visually-hidden message?

    The shapes are decoration. A visually hidden status message gives screen reader users the information that sighted users get from the skeleton.
  2. 2. What does data-bs-target="#toc" tell ScrollSpy?

    The target attribute points to the navigation whose links are highlighted as the matching sections become current.
  3. 3. How can the last, short section become active?

    A section that is shorter than the active band at the bottom of the scroll area can never reach it, so bottom padding or spacing helps.
  4. 4. What is scroll-margin-top used for in a page with a sticky header?

    scroll-margin-top offsets the scroll target so the heading stays visible below the sticky header.
  5. 5. When should you prefer a skeleton over a spinner?

    Skeletons suit known layouts and short waits. Spinners fit unknown layouts or button actions, and instant results need neither.

Summary

  • Placeholders draw skeleton shapes; make them mirror the final layout, hide them from assistive technology and announce loading with visually-hidden text, aria-live and aria-busy.
  • Replace the skeleton with real content when data arrives, and show skeletons only when a wait is long enough to notice.
  • ScrollSpy highlights the link of the section in view; configure it with data-bs-target, data-bs-root-margin, data-bs-smooth-scroll and listen for activate.bs.scrollspy.
  • Pin the sidebar with sticky-top and a top offset equal to your header height; use scroll-margin-top on targets.
  • Refresh the plugin after changing sections dynamically, and never depend on the highlight alone for navigation.

Next lesson: Customizing with CSS Variables, where you restyle Bootstrap without compiling Sass.