StepOptions

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:35

The options for the step

Properties

advanceOn?

optional advanceOn?: StepOptionsAdvanceOn

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:65

An action on the page which should advance shepherd to the next step. It should be an object with a string selector and an event name

const step = new Step(tour, {
  advanceOn: { selector: '.some .selector-path', event: 'click' },
  ...moreOptions
});

event doesn’t have to be an event inside the tour, it can be any event fired on any element on the page. You can also always manually advance the Tour by calling myTour.next().

arrow?

optional arrow?: boolean | StepOptionsArrow

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:70

Whether to display the arrow for the tooltip or not, or options for the arrow.

attachTo?

optional attachTo?: StepOptionsAttachTo

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:51

The element the step should be attached to on the page. An object with properties element and on.

const step = new Step(tour, {
  attachTo: { element: '.some .selector-path', on: 'left' },
  ...moreOptions
});

If you don’t specify an attachTo the element will appear in the middle of the screen. If you omit the on portion of attachTo, the element will still be highlighted, but the tooltip will appear in the middle of the screen, without an arrow pointing to the target.

beforeShowPromise?

optional beforeShowPromise?: () => Promise<unknown>

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:76

A function that returns a promise. When the promise resolves, the rest of the show code for the step will execute.

Returns

Promise<unknown>

buttons?

optional buttons?: readonly StepOptionsButton[]

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:82

An array of buttons to add to the step. These will be rendered in a footer below the main body text.

cancelIcon?

optional cancelIcon?: StepOptionsCancelIcon

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:87

Should a cancel “✕” be shown in the header of the step?

canClickTarget?

optional canClickTarget?: boolean

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:96

A boolean, that when set to false, will set pointer-events: none on the target.

The blocking is delivered by shepherd.css (via the shepherd-target-click-disabled class), so it has no effect if you have opted out of Shepherd’s stylesheet without providing an equivalent rule.

classes?

optional classes?: string

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:101

A string of extra classes to add to the step’s content element.

data?

optional data?: Record<string, unknown>

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:110

Arbitrary, JSON-serializable data to associate with the step. Shepherd does not use this value internally; it is a place to store your own metadata (for example analytics ids, or context produced by a tour generator) and read it back from step.options.data in event handlers and button actions.

extraHighlights?

optional extraHighlights?: readonly string[]

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:123

An array of extra element selectors to highlight when the overlay is shown The tooltip won’t be fixed to these elements, but they will be highlighted just like the attachTo element.

const step = new Step(tour, {
  extraHighlights: [ '.pricing', '#docs' ],
  ...moreOptions
});

floatingUIOptions?

optional floatingUIOptions?: object

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:191

Extra [options to pass to FloatingUI]https://floating-ui.com/docs/tutorial/

This includes strategy, the CSS position used for the step element, which defaults to 'absolute'. Centered steps are always position: fixed and ignore strategy – a step counts as centered when it has no attachTo at all, or when its attachTo is missing either element or on.

middleware?

optional middleware?: (false | { name: string; options?: any; fn: Promisable<MiddlewareReturn>; } | null | undefined)[]

Array of middleware objects to modify the positioning or provide data for rendering.

placement?

optional placement?: Placement

Where to place the floating element relative to the reference element.

platform?

optional platform?: Platform

Custom or extended platform object.

strategy?

optional strategy?: Strategy

The strategy to use when positioning the floating element.

highlightClass?

optional highlightClass?: string

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:129

An extra class to apply to the attachTo element when it is highlighted (that is, when its step is active). You can then target that selector in your CSS.

id?

optional id?: string

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:134

The string to use as the id for the step.

label?

optional label?: StringOrStringFunction

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:153

The aria-label for the step’s dialog, used to give the step an accessible name when it has no visible title. A step with neither gets no naming attribute at all, so its dialog has no accessible name and screen readers announce it without one.

- string
- `Function` to be executed when the step is built. It must return a string.

Ignored when title is set: the title already supplies the accessible name via aria-labelledby, which outranks aria-label in the accessible name computation. In that case a function-valued label is not invoked at all.

An empty or whitespace-only value omits the attribute rather than emitting an accessible name that assistive technology treats as empty.

modalOverlayOpeningPadding?

optional modalOverlayOpeningPadding?: number

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:158

An amount of padding to add around the modal overlay opening

modalOverlayOpeningRadius?

optional modalOverlayOpeningRadius?: number | { bottomLeft?: number; bottomRight?: number; topLeft?: number; topRight?: number; }

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:163

An amount of border radius to add around the modal overlay opening

modalOverlayOpeningXOffset?

optional modalOverlayOpeningXOffset?: number

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:175

An amount to offset the modal overlay opening in the x-direction

modalOverlayOpeningYOffset?

optional modalOverlayOpeningYOffset?: number

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:180

An amount to offset the modal overlay opening in the y-direction

scrollTo?

optional scrollTo?: boolean | ScrollIntoViewOptions

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:196

Should the element be scrolled to when this step is shown?

scrollToHandler?

optional scrollToHandler?: (element) => void

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:202

A function that lets you override the default scrollTo behavior and define a custom action to do the scrolling, and possibly other logic.

Parameters

element

HTMLElement

Returns

void

showOn?

optional showOn?: () => boolean

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:208

A function that, when it returns true, will show the step. If it returns false, the step will be skipped.

Returns

boolean

skipMissingElement?

optional skipMissingElement?: boolean

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:226

When true, a step whose attachTo.element selector (or function locator) does not resolve to an element in the DOM is skipped, advancing to the next step (or the previous step when navigating backwards) instead of being shown centered. If all remaining steps are skipped, the tour completes (going forward) or cancels (going backward), mirroring the showOn semantics. Can be set on defaultStepOptions to apply to every step. Combine with waitForElement to give the element time to appear before skipping. Steps without an attachTo element are never skipped, since they are intentionally centered.

Note that the target is looked up before the step’s own beforeShowPromise and before-show handlers run, so an element that those handlers create is not visible to this check. Use beforeShowPromise on its own for targets the step itself renders.

text?

optional text?: StepText

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:237

The text in the body of the step. It can be one of four types:

- HTML string
- Array of HTML strings
- `HTMLElement` object
- `Function` to be executed when the step is built. It must return one of the three options above.

title?

optional title?: StringOrStringFunction

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:246

The step’s title. It becomes an h3 at the top of the step.

- HTML string
- `Function` to be executed when the step is built. It must return HTML string.

waitForElement?

optional waitForElement?: number

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:260

The maximum amount of time, in milliseconds, to wait for the attachTo.element to appear in the DOM before showing the step. The DOM is watched with a MutationObserver (falling back to polling when it is unavailable), so the step attaches as soon as the element appears. If the timeout expires, the step falls back to its default behavior: skipped when skipMissingElement is true, otherwise shown centered.

The wait starts before the step’s own beforeShowPromise and before-show handlers run, so it cannot observe a target that those handlers create, and a function locator is re-evaluated on each DOM change until it resolves.

when?

optional when?: StepOptionsWhen

Defined in: docs-src/node_modules/shepherd.js/src/step.ts:272

You can define show, hide, etc events inside when. For example:

when: {
  show: function() {
    window.scrollTo(0, 0);
  }
}