Skip to main content

Building on Next.js

  • Next
  • NextJS


Dopt provides a React SDK and React components that work seamlessly with Next.js. You can use Dopt components to get started with customizable pre-built UI or go headless and integrate Dopt with your own UI components.


Install @dopt/react and any Dopt React components that you might want to use (like @dopt/react-modal).

npm install @dopt/react @dopt/react-modal

If you are using the pages router and pre-built UI from Dopt React components, you will need to transpile the Dopt React components you are planning on using:

/** @type {import('next').NextConfig} */
const nextConfig = {
transpilePackages: [
// 👇 Add the Dopt React components you are using
// 👇 These are dependencies that also need to be transpiled

module.exports = nextConfig

If you are on Next.js 12, you will need to use next-transpile-modules to transpile our component packages. Learn more →

Initialize Dopt

Initialize Dopt by adding the DoptProvider to your Next.js app.

import type { AppProps } from 'next/app';

import { DoptProvider } from '@dopt/react';

export default function App({ Component, pageProps }: AppProps) {
return (
flows={{ 'onboarding': 1 }}
<Component {...pageProps} />

Additionally, make sure to render the DoptProvider within a client-side component.

Because the DoptProvider relies on useEffect hooks to set up sockets and perform data fetches and updates, it needs to be managed by a component which specifies use client.

Using components

Dopt's React components make it super easy to get up and running with some basic UI to build your own experiences. They can easily be styled or themed to make them match your product and brand.

Import the component and its associated hook (such as useModal) and then add the component to your page:

import Modal, { useModal } from '@dopt/react-modal';

export default function Page() {
const modal = useModal('my-flow.four-pandas-jam');

return (
<h1>Hello Next.js!</h1>

<Modal.Root active={}>
<Modal.Overlay />
<Modal.DismissIcon onClick={modal.dismiss} />
<Modal.DismissButton onClick={modal.dismiss}>
<Modal.CompleteButton onClick={modal.complete}>

If you are getting Next.js errors about CSS imports, make sure you have properly configured Next.js to transpile the Dopt component packages and related dependencies.

Using headless components

Dopt's React components can also be used headlessly. This is quite powerful for when you want to use your own components with Dopt rather than using our pre-built UI.

Import the component's hook from the /hooks import (such as import { useModal } from '@dopt/react-modal/hooks') and then use its state and content in your own UI component:

import { useModal } from '@dopt/react-modal/hooks';
/** ^^^^^
* The `/hooks` import will not include any CSS in your app */
import RichText from '@dopt/react-rich-text';

export default function Page() {
const modal = useModal('my-flow.four-pandas-jam');

return (
<h1>Hello Next.js!</h1>

<dialog open={}>
<button onClick={modal.dismiss}>{modal.dismissLabel}</button>
<button onClick={modal.complete}>{modal.completeLabel}</button>

Using the React SDK

The React SDK gives you access to both block and flow state amongst other things which allows you to build rich UI experiences. Learn more about it in our React SDK guide →