Shepherd.js — Guide Users Through Your App Step by Step

Introduction

Shepherd.js is a library for building user onboarding tours and feature walkthroughs. It uses Floating UI for smart element positioning and provides a step-based API where each step can attach to a DOM element, display rich HTML content, and include action buttons.

What Shepherd.js Does

• Creates multi-step guided tours attached to specific UI elements
• Positions tooltips and modals intelligently with Floating UI collision detection
• Supports modal overlays that highlight the active element
• Provides lifecycle hooks for each step (before show, after hide, on cancel)
• Includes framework wrappers for React, Vue, and Angular

Architecture Overview

Shepherd.js manages a tour as an ordered list of step objects. Each step references a target DOM element and a popover configuration. The library delegates positioning to Floating UI, which calculates optimal placement while avoiding viewport clipping. An overlay layer dims the rest of the page and blocks interaction outside the highlighted element.

Self-Hosting & Configuration

• Install via npm and import the default CSS theme
• Create a Tour instance with global defaults for all steps
• Add steps with attachTo, text, title, and buttons properties
• Customize the overlay color and opacity via CSS variables
• Use tour.on() to listen to events like complete, cancel, and show

Key Features

• Floating UI integration for reliable cross-browser positioning
• Modal overlay with element highlighting and click-outside blocking
• Built-in accessibility with focus trapping and ARIA attributes
• Theming via CSS custom properties or full CSS overrides
• Framework-specific packages for React, Vue, Ember, and Angular

Comparison with Similar Tools

• Driver.js — Lighter and zero-dependency; Shepherd.js is more feature-rich with modal overlays
• Intro.js — Similar feature set but requires a commercial license; Shepherd.js is MIT-licensed
• React Joyride — React-only; Shepherd.js is framework-agnostic with optional framework wrappers
• Walktour — Smaller React library; Shepherd.js handles more complex multi-page tours

FAQ

Q: Can I use Shepherd.js with React? A: Yes. Install react-shepherd for a hook-based API that wraps Shepherd.js tours.

Q: How do I style the tour steps? A: Override the default CSS classes or use CSS custom properties to change colors, fonts, and spacing.

Q: Can steps target dynamically rendered elements? A: Yes. Use the beforeShowPromise hook to wait for elements to appear before attaching a step.

Q: Does it support multiple tours on one page? A: Yes. Create separate Tour instances and start them independently.

Sources

• https://github.com/shipshapecode/shepherd
• https://shepherdjs.dev