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

> A JavaScript library for creating guided tours and onboarding flows with customizable steps, themes, and intelligent element positioning.

## Install

Save as a script file and run:

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

## Quick Use
```bash
npm install shepherd.js
```
```js
import Shepherd from "shepherd.js";
import "shepherd.js/dist/css/shepherd.css";

const tour = new Shepherd.Tour({ defaultStepOptions: { cancelIcon: { enabled: true } } });
tour.addStep({ title: "Welcome", text: "Let me show you around.", attachTo: { element: ".header", on: "bottom" }, buttons: [{ text: "Next", action: tour.next }] });
tour.start();
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-5acb2ba1
Author: Script Depot