How we Use Storyblok to Improve Onboarding

Great onboarding experiences don't just happen. They're crafted, iterated, and refined over time. But what happens when the people who understand your users best can't easily update the onboarding experience?

We faced exactly this situation. We relied on a third-party tour tool for onboarding, but it created friction: our marketing team had to learn a separate platform, update cycles were slow, and we had limited control over styling.

So we rebuilt our tour system using the obvious choice: Storyblok.

This article describes the challenges that sparked the change, how we architected the solution, and the new workflow that empowers our marketing team to iterate quickly without relying on developers.

The problem

Our previous onboarding experience was based on a third-party service. It worked well, but presented the following challenges:

• Learning a new tool. Our marketing team had to learn to use a separate platform to update tour content. Every new team member had to be onboarded, which is ironic.
• Content bottlenecks. Updating tour copy often meant waiting on engineering or struggling with unfamiliar interfaces. Quick iterations became slow cycles.
• Limited control. Targeting specific UI elements or customizing the experience to match our brand and design patterns was difficult.

We needed something that allowed the marketing team to work independently, that interacted seamlessly with Storyblok, and matched our UI and design system.

The solution

That’s when we realized the obvious solution: a headless CMS we’re all familiar with, named Storyblok. Our Marketing team already uses Storyblok to manage content, so there's no new tool to learn. They can jump in and start editing immediately. Whether it’s the tour content, images, or the actual UI components presented in the tour, they manage everything directly in Storyblok.

Tours look and feel native to our application because they are; they are stories that use our design system. For our customers, this means a seamless, on-brand experience:

The only question was how to build a solid technical solution without reinventing the wheel. The answer was to develop a modular “mini app” that’s powered by the main Storyblok application but is fully isolated from the rest of the codebase. As a standalone add-on, we can develop and test the tour app independently without risking side effects elsewhere. It’s easy to maintain, update, and implement across different projects.

How it works

Under the hood, we use Intro.js, an open source customer onboarding library that controls the tour’s navigation and display, while the main Storyblok application handles rendering and interaction. The content is managed entirely in Storyblok.

From plain HTML strings to a Vue component

We wanted full control over what renders inside each step. This means custom Vue components that use our design system, rich text rendering, images, step counters, conditional navigation buttons, and callback-driven actions.

Intro.js renders tooltip content as plain HTML strings. Its API expects a title and intro per step, which it then injects into a fixed tooltip template. There’s no built-in mechanism to mount a Vue component, pass reactive props, or use your brand’s design system and layout inside a tooltip.

That’s when we decided to let Intro.js handle what it does well — overlay positioning, element highlighting, and step sequencing, and take over tooltip content rendering.

Our app intercepts the moment Intro.js renders a tooltip and grabs a reference to the container it uses for the content. It then mounts a standalone Vue app into that container. When a step is activated, we create a new Vue application instance, render the specified component with its props, and mount it into the tooltip container.

This gives us a fully functional Vue component tree within each tooltip. In practice, each step specifies a Vue component and its props rather than an HTML string. Our composable maps these step definitions back into Intro.js-compatible steps, acting as a bridge between our step model and Intro.js’ lifecycle.

Each tour is a story

Finally, our non-technical experts can edit the tour steps however they choose — the content, as well as other parts of the tour.

Target reference

Select which UI element to highlight during the user’s tour navigation.

Position

Set the position of the tour step against the target reference element.

Skip

Let users skip steps or close the tour.

Step counter

Display the user’s current progress in the tour experience.

Timed replay

Reopen a particular step after a certain period.

No code. No engineering tickets. No bottlenecks.

Trade-offs

This approach doesn’t come without cost. Creating and tearing down Vue app instances per step adds overhead compared to rendering static HTML.

That said, the alternative — duplicating our UI components as raw HTML strings, losing reactivity, and maintaining parallel rendering paths — is far more costly in the long term.

Takeaways

Our marketing team is now in the driver’s seat of the onboarding tour: from copy and asset updates to refining the overall user experience. They don’t require developers’ involvement. Our users, in turn, enjoy a polished, on-brand onboarding experience that feels native to Storyblok.

And what about us? We maintain a reusable module that's isolated, maintainable, extensible, and reusable across other projects.

When your CMS is flexible enough, you can solve more than just “content” problems. The composable nature of a headless CMS means that you can expand the meaning of content, transforming your space from a repository for managing static pages into a true content operations platform.