Feature: Using Custom Component for the Step Dialog Box

[alvintheodora]

Hi, I'd like to ask if it is possible to use our own custom Component, (for example, I have my own Vue Component) for the step dialog box.
Because so far what I've read in the Github Issue and Docs, is that we can only override the styles of the built-in class of the step dialog box or specify custom class for the step options, but not render our own Component to it.
Thank you.

[RobbieTheWagner]

@alvintheodora you can pass any HTML you want to it, so you have to manually handle the rendering of your component to HTML and then you can pass it in.

[alvintheodora]

Hi @RobbieTheWagner , how do we pass that ? Do we have any sample demo for it?
Thanks

[chuckcarpenter]

Following up here — sorry your question about a demo sat this long.

To add the detail that was missing from my earlier answer: you don't actually have to render your component to an HTML string first. text also accepts a live HTMLElement, and Shepherd appendChilds it rather than assigning innerHTML. Because the node is moved rather than serialized, your event handlers, reactivity, and component state come along with it.

StepText (step.ts#L29-L33) is string | ReadonlyArray<string> | HTMLElement | (() => …), and the branch that matters is shepherd-text.ts#L21-L25:

if (isHTMLElement(text)) {
  el.appendChild(text);
} else {
  el.innerHTML = text as string;
}

So mount your Vue component into a detached div and hand Shepherd that div:

import { createApp } from 'vue';
import Shepherd from 'shepherd.js';
import 'shepherd.js/dist/css/shepherd.css';
import StepBody from './StepBody.vue';

const tour = new Shepherd.Tour({ useModalOverlay: true });

const host = document.createElement('div');
const app = createApp(StepBody, { tour }); // props go here; call tour.next() from inside
app.mount(host);

tour.addStep({
  id: 'custom',
  attachTo: { element: '.target', on: 'bottom' },
  arrow: false,
  text: host, // live node — moved into the step, not serialized
  buttons: []
});

const unmount = () => app.unmount();
tour.on('complete', unmount);
tour.on('cancel', unmount);

tour.start();

Three notes on why it's shaped that way:

• Mount once, outside the step, rather than inside a text function. The step element is torn down and rebuilt on every show (step.ts#L701-L706), and appendChild moves your existing node into the newly built one, so the same app instance survives back/next. Creating it inside a text function would spin up a fresh Vue app every time the step is shown.
• Unmount on the tour's complete/cancel, not on the step's destroy. In 15.2.3 that rebuild-on-show path goes through the step's public destroy(), so a step.on('destroy', …) handler would fire on every re-show and tear your app down mid-tour. (That's fixed on main but isn't in a release yet — the tour-level events are the safe hook either way.)
• Mount before addStep. Shepherd snapshots the focusable elements inside the dialog when it builds the step (shepherd-element.ts#L155-L162), so your component's buttons need to be rendered by then to land in the tab order.

What you can't replace is the surrounding chrome — <dialog class="shepherd-element"> and .shepherd-content are Shepherd's own DOM. But everything inside it is opt-out: no title/cancelIcon means no header, an empty buttons array means no footer (shepherd-content.ts#L16-L29), and arrow: false drops the arrow (it defaults to true, step.ts#L675). With those off, your component owns the entire body.

If you'd like the tour lifecycle itself to feel more Vue-idiomatic, vue-shepherd wraps it in a composable. It doesn't render steps as components, but it composes fine with the above.

Two caveats worth stating plainly: this comes from reading the v15.2.3 source rather than from a running repro, and while the Shepherd-side option names and types above are checked against the TypeScript definitions, the createApp/mount/unmount usage is just standard Vue 3 and I haven't run it.

I'm closing this out and have opened #3479 to get it into the docs — that gap is on us, not something you should have had to ask twice for. If the above doesn't work in a real app, comment here and I'll reopen.