Learn how to implement Knock guides in a Vue.js application using the Knock JavaScript SDK.
In this tutorial we'll walk through how to implement Knock guides in a Vue.js application. Knock's guide provider and hooks are built for React, so we'll use the underlying Knock JavaScript SDK directly to recreate the same behavior using Vue composables.
The Knock React SDK uses a provider/hook pattern (KnockProvider, KnockGuideProvider, useGuide). In Vue.js, you replicate this with provide/inject and composables.
React
Vue
KnockProvider
A KnockProvider.vue component that uses Vue's provide/inject.
KnockGuideProvider
Included in KnockProvider.vue.
useGuide() hook
A useGuide() composable.
The Knock client must initialize in a specific sequence before guides are available: the Knock client initializes first, the user authenticates, then the guide client initializes and fetches guides.
Implementation
#
1
Install required packages and dependencies.
2
Create the Knock client composable.
This composable initializes the Knock client and authenticates the user. It uses shallowRef for the client instance — rather than reactive() — to avoid TypeScript errors from Vue's deep unwrapping of class internals.
3
Create the guide client composable.
This composable initializes the guide client, subscribes to guide updates, and exposes methods for fetching and selecting guides. The store subscription keeps Vue's reactive state in sync with the guide client's internal store.
4
Create the provider component.
The provider component initializes Knock, authenticates the user, and makes the guide client available to all child components via provide. It also watches knock.isReady to handle cases where authentication completes after mount.
Use the provider at the root of any view that needs guide functionality:
5
Create the useGuide composable.
The useGuide composable mirrors the React useGuide hook — it fetches a single guide by type or key. It takes the knockGuides instance as a parameter, which the calling component retrieves via inject from KnockProvider.
Each guide step exposes a content object whose shape is determined by your message type schema. Common properties include:
Marks the guide as interacted, recording a click event or other user interaction, with optional metadata.
markAsArchived()
Marks the guide as archived, removing the guide from eligibility for the user.
6
Build a guide component.
With the composables in place, you can build components to render guides. This example shows a banner component that renders a guide, tracks engagement, and handles dismissal.
7
Secure the client with user tokens.
The implementation above authenticates users by id only. For production use, you should also pass a user token — a short-lived JWT signed by your backend — to verify that the client is authorized to act on behalf of the user.
Troubleshooting
#
See debugging guides for general troubleshooting guidance related to guide activation and targeting. You may also encounter these Vue-specific issues:
Issue
Solution
Guides are not appearing after authentication.
Check that knock.knockClient.value exists before calling initializeGuideClient. The watch on knock.isReady in KnockProvider.vue handles cases where the client becomes ready asynchronously.
The store subscription is not updating components.
Confirm that state.guideClient.store.subscribe is being called after initializeGuideClient.