Rendering guides | Knock Docs

Once you've created a guide, you'll need to render it in your product using the guides API. This involves fetching the guide data from Knock and displaying it to your users based on their eligibility. You can render guides using Knock's client-side SDKs, which provide built-in state management and helper methods, or by directly calling the guides API to build a custom implementation. Below we cover both approaches and how to filter guides to show the right content to your users.

Fetching guides

You can fetch guides using Knock's client-side SDKs or by directly calling the guides API.

Client-side SDKs

Knock exposes a set of client SDKs that provide helpers and logic to make it easier to work with guides in your product. Simplify your guides implementation by leveraging the SDK's guides provider and associated methods for accessing the fetched guides and their steps.

		React	React Native	JavaScript
Features	Pre-built UI components
	Hooks for building custom UI components
	State management for guides
	Low-level API bindings and state management for building custom UI components

Key SDK resources

When working with Knock's SDKs to fetch and render guides, you'll use the following components and hooks:

KnockGuideProvider. Provider component that fetches guides and manages guide state.
useGuide. Hook to fetch a single guide by type or key.
useGuides. Hook to fetch multiple guides.
useGuideContext. Hook to access the guide client for advanced use cases.

Guides API

You can also directly call the guides API to fetch guides and render them in your product. This approach gives you flexibility and full control over the rendering process, but requires you to build your own state management and UI components. We highly recommend using the SDKs as they provide a robust set of tools and helpers for working with guides.

Filtering guides

You can fetch guides by either a type or a key to select a guide from the fetched set of guides. Here's how to think about choosing between these two selectors:

Selector	Filters by	When to use
`key`	Guide `key`	Render a specific instance of a guide.
`type`	Message type `key`	Render any guide of this message type.

When multiple guides exist for a single type (e.g, a generic "Banner" component that could be used multiple times across many guides), Knock will prioritize guides chronologically, starting with the oldest guide. You can control the order of prioritzation by ordering your guides in the Knock dashboard.

Frequently asked questions

The useGuide hook fetches a single guide at a time. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI.

The useGuides hook fetches one or more guides, subject to eligibility criteria. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar.

To render multiple guides in a single component, use the useGuides hook instead of useGuide. The plural useGuides hook returns an array of guides that you can iterate over to render multiple instances.

This approach is useful for displaying lists of announcements, changelog entries, or other content where multiple guides should be visible simultaneously. You can filter guides by type to get all guides using a specific message type, or omit the filter to get all eligible guides for the user.

Note: useGuides returns guides ordered per the priority set in the dashboard, but it bypasses throttling rules since it's intended to return multiple guides.

The display_sequence array in the API response shows all active guides, not just the guides currently eligible for the user. This includes:

Guides the user has already seen or interacted with.
Guides that don't match the current page's activation rules.
Guides where targeting conditions aren't met.
Guides that are active in the group but filtered out by your query parameters.

The display_sequence represents the priority order for all guides in the group. The actual rendered guides depend on eligibility criteria including targeting conditions, activation location rules, ordering and throttling rules, engagement status, and any filters you've applied via the type query parameter.

To see which guides are actually eligible to be rendered, check the entries array in the API response, which contains only the guides that match all criteria for the current user and context.