How to add contextual help in Next.js project

Providing contextual help in your Next.js application enhances user experience by delivering relevant guidance exactly when and where it's needed. Whether you're building a complex dashboard, an e-commerce site, or a SaaS platform, well-placed tooltips, modals, and inline hints can reduce confusion and improve user engagement.

In this guide, we’ll walk you through the best ways to implement contextual help in Next.js, covering several common approaches. By the end, you'll be equipped with practical strategies to make your app more intuitive and user-friendly. Let’s dive in!

When it comes to adding documentation to your product, there are several approaches to consider:

1. Inline documentation
2. Linking to an external documentation site
3. Building your own solution
4. Simplifying everything with SideHint

---

1. Inline Documentation

Inline documentation is a great starting point, especially when your product is in its early stages and hasn’t yet achieved product-market fit.

It’s the simplest solution, requiring no external tools.

For example, Stencil, a customer of ours, provides an image generation service with a template editor. Users can create base templates for image generation. As Stencil introduced more sophisticated features, their template editor grew increasingly complex, leaving no space for inline documentation.

This highlights a key drawback of inline documentation: it’s tightly coupled with your application’s codebase. Updating or adding documentation often requires redeploying the entire application.

Inline documentation works best for features that are stable and easy to explain concisely. If a feature doesn’t change frequently, embedding help text directly into the UI—through tooltips, labels, or short descriptions—ensures that users always have immediate access to relevant information without needing to search elsewhere.

This approach is particularly effective when:

• The feature has a simple learning curve and can be understood with a brief explanation.
• Users frequently interact with the feature, making external documentation unnecessary.
• The information is unlikely to become outdated, reducing maintenance overhead.

A great example of effective inline documentation is found in ChatGPT settings, where contextual help is provided directly within the UI. Many of these settings include short descriptions that clarify their purpose, ensuring users can quickly understand and adjust them without needing external documentation.

This approach works well because most settings are straightforward, making them easy to explain in a sentence or two. Instead of overwhelming users with unnecessary details, ChatGPT provides just enough information at the right moment, keeping the interface clean and user-friendly.

---

2. External Documentation Site

Hosting your product documentation on an external platform like GitBook provides several key advantages, especially for growing projects that require well-structured, easily maintainable, and user-friendly help resources.

Centralized and Organized Content

Platforms like GitBook allow you to create a dedicated knowledge base, making it easy for users to find the information they need. With features like search functionality, categories, and nested pages, your documentation remains structured and accessible.

Easier Updates and Versioning

Unlike inline documentation, which requires code changes to update, external sites let you edit and publish content independently. This is especially useful for:

• Frequently changing features
• Versioned documentation for different product releases
• Keeping historical records of past functionalities

Rich Formatting and Interactive Content

GitBook supports Markdown, images, videos, and embeds, allowing you to create step-by-step guides, FAQs, and tutorials with visuals that enhance comprehension. This is crucial for complex workflows that can't be explained with a simple tooltip.

Collaboration and Access Control

Many external documentation platforms support team collaboration, enabling multiple contributors to update content. You can also set permissions, restricting certain documentation to internal teams or premium users.

SEO Benefits and Public Discoverability

An external documentation site can improve your product’s SEO visibility, making it easier for users to find answers via search engines. This reduces customer support requests and improves user satisfaction.

By using GitBook or a similar platform, you provide a scalable, maintainable, and user-friendly solution for your product documentation, ensuring users always have access to the most up-to-date information.

However, not every feature in your application warrants a full page of explanation. Overloading users with excessive external documentation for small features can feel overwhelming.

The biggest downside of linking to an external site is the poor user experience (UX). Redirecting users to a different site breaks their focus, pulling them away from your application.

---

3. Build Your Own Solution

If you’re developing a custom application, building your own documentation solution might seem like a reasonable choice. However, doing so can take significant time and energy, distracting you from shipping your core product.

Don’t reinvent the wheel.

---

4. Using SideHint for In-App Contextual Help

SideHint provides the easiest solution by helping to create and manage contextual helps to document your product features without much drawbacks of from the previous approaches.

SideHint is an excellent choice if:

• You need more than just a tooltip to provide rich contextual help for features in your product.
• The content is too brief for a traditional knowledge base but still valuable enough to be surfaced within the app.
• You want to dynamically manage documentation without hardcoding it into your codebase.
• Keeping users engaged within your app—without redirecting them to an external site—is a priority.

If you answered YES to some of them, please reading to see how you can add contextual help to your Next.js application. (Even if you answered NO, just continue to read them :))

1. Identify feature to document

Before writing contextual documentation, it's important to first identify which feature needs to be documented. This is typically a feature that users find complex or confusing.

A great way to determine this is by analyzing frequent support tickets—if users often ask how to use a particular feature, it’s a strong indicator that contextual help is needed.

2. Write your documentation

Log in to your SideHint account and add your website’s domain if you haven’t already. Create your panel, which will serve as the foundation for your contextual help.

SideHint offers a block-based editor designed to simplify documentation writing.

From experience, contextual help should be concise but not necessarily short—it should provide just enough guidance to retain user focus without overwhelming them. Otherwise, users may become frustrated and abandon the task.

2. Create a Trigger for the Sidebar Widget

A trigger is an element on your page (like "Learn More" or "Help") that, when clicked, opens the sidebar containing your documentation.

While it’s ideal to use a unique element ID for the trigger, it’s not strictly required. You can use your browser’s inspect tool to locate the desired element for the trigger.

1. In Chrome or Firefox, right click on the page and select Inspect. You can also use the keyboard shortcut: Ctrl/Mac + Shift + C
2. Hover over the element that you like to make it as a trigger
3. The corresponding element will be highlighted in the inspect tool. Right click on the higlighted section.
4. Select Copy > Copy selector

Next, paste the result to the trigger section in the editor and save your panel.

---

3. Add the Embed Code to Your Website

Once your documentation is ready, copy the embed code and paste it into your application. This step only needs to be done once—future updates won’t require re-embedding.

For a Next.js application, you’ll need to modify the embed code slightly to align with Next.js-specific functionality. Since Next.js uses React and its virtual DOM, SideHint automatically listens for DOM changes and dynamically injects triggers. This ensures that the triggers remain functional, even when components remount.

  <Script src="https://app.sidehint.com/assets/sdk.js" type="text/javascript" defer />
  <Script src="https://app.sidehint.com/s/embed.js?s=XXXXXXXXXXXXXXXXXXXXXX" type="text/javascript" defer />

You want to do this in your root layout and ensure that you're using the Script tag from NextJS so that it gets injected properly to the head.

---

By choosing SideHint, you’ll simplify documentation without sacrificing UX or developer efficiency.