In-App UI

React

UI components

Modal

How to ship an in-app notification modal using our pre-built guides component.

Our @knocklabs/react library comes with a pre-built modal component you can drop into your application.

The modal component enables you to display important notifications, announcements, or interactive content in a focused overlay that appears above your application's main content.

Getting started

#

To use the modal component, you'll need:

An account on Knock
A guide channel set up in your Knock dashboard
A guide created using the "Modal" message type

Installing dependencies

#

Basic usage

#

1

Setup the KnockGuideProvider

First, wrap your application with the KnockProvider and KnockGuideProvider. The KnockGuideProvider requires a channelId. You can find your guide channel ID on the integrations page in the dashboard under "Channels".

2

Import Knock's pre-built Modal component and place it inside the KnockGuideProvider near the top of your application's component tree. The <Modal/> component is most effective when placed in the root layout of your application as it ensures your modal is available to render on every page of your application.

3

Mount the component

The Modal component will mount automatically when a user becomes eligible for a guide created using the modal message type.

Remember, for a user to be eligible, they must match the targeting rules of the guide, and they must be in a page in your application that matches the activation rules of the guide.

You can learn more about guide targeting and activation rules in the creating guides page.

#

The pre-built modal message type supports three variants for different use cases:

Default. A dismissible modal with no action buttons.
Single action. A dismissible modal with a single action button.
Multi-action. A dismissible modal with two action buttons.

Handling user engagement

#

The modal component handles user engagement tracking automatically. Here's an overview of what user behavior maps to which engagement statuses tracked in Knock.

Seen. The modal has been rendered to (seen by) the user.
Interacted. The user has interacted with (clicked) the modal. Dismissing the modal does not count as an interaction.
Archived. The modal has been archived (dismissed) by the user.

#

Knock provides multiple levels of customization for the modal component, from simple theming to complete custom implementations. Choose the approach that best fits your needs:

CSS variable theming

#

The easiest way to customize the modal's appearance is by overriding CSS variables. Knock provides CSS variables prefixed with --knock-guide- that are specifically designed for theming all of Knock's pre-built guide components.

This approach enables you to quickly match your brand colors and basic styling without diving into complex CSS overrides. The --knock-guide-accent variable is particularly useful for theming buttons and interactive elements.

CSS class overrides

#

For more granular control, you can override the specific CSS classes used by the modal component. All Knock guide components use classes that start with prefixes specific to the component type.

Individual subcomponents

#

For maximum flexibility while still leveraging Knock's functionality, you can use the individual subcomponents to compose your own modal. This approach gives you full control over the layout and styling while maintaining the guide behavior:

This approach is ideal when you want to customize a piece of the pre-built component or change its structure.

Building your own component

#

For complete control over both functionality and appearance, you can build your own modal component using the useGuide hook. This approach gives you the most flexibility but requires implementing all the modal behavior yourself:

#