Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 58 ยท 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.