Rendering guides

In this document you'll learn how to render guides in your product using the guides API.

Knock exposes a useGuide hook, which accepts either a type (corresponding to a message type key) or a key (a specific guide key) to select a guide from the fetched set of guides.

Here's how to think about when to use both of these:

• key: If you want your component to only ever render a specific instance of a guide, like when building an embedded UI, then use the key selector.
• type: If you want to render any guide that uses this message type, like when building a generic "Banner" component that could be used multiple times across many guides, but only ever shows a single banner at a time, then use the type selector.
• When multiple guides exist for a single type, by default we return the earliest created guides first then the most recently created guide last. Alternatively, you can control this behavior and manually configure the relative priority of guides by ordering guides in the Knock dashboard.

Knock also exposes a useGuides hook that returns an array of guides matching provided filter criteria. Use the useGuides hook when you want to select and render multiple guides of a single type at the same time. The useGuides hook will return guides in the same order as the useGuide hook, whether by the default order or the manually configured order. Each guide in a returned guides array has a getStep helper method that will return its step with the message content.

Each guide step exposes methods to work with engagement tracking:

• step.markAsSeen: mark that the user has seen the guide, but not yet interacted with it.
• step.markAsInteracted: mark the step as interacted with, optionally passing metadata about the interaction
• step.markAsArchived: mark the step as archived, making it no longer visible for the user.

If you need to understand the current status of the guide step, you can access the state under step.message which will expose a StepMessageState including:

• seen_at: when the message was last seen (timestamp or null)
• read_at: when the message was last read (timestamp or null)
• interacted_at: when the message was last interacted
• archived_at: when the message was last archived

In certain cases, you may need to drop down to operate on the guide client, which is the state management layer automatically created when you mount a GuideProvider.

You can always access the guide client by using the useGuideContext hook:

One use case for accessing the guide client is to force a refetch of the users eligible guides, which you can do through the guideClient.fetch() method.