Skip to main content

Building on Next.js

  • Next
  • NextJS

Overview​

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.

Installation​

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:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: [
    // 👇 Add the Dopt React components you are using
    '@dopt/react-modal',
    // 👇 These are dependencies that also need to be transpiled
    '@dopt/react-theme',
    '@dopt/react-rich-text',
    '@dopt/core-theme',
    '@dopt/core-rich-text',
  ],
}

module.exports = nextConfig
info

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.

pages/_app.tsx
import type { AppProps } from 'next/app';

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

export default function App({ Component, pageProps }: AppProps) {
  return (
    <DoptProvider
      userId="USER_ID"
      apiKey="BLOCKS_API_KEY"
      flows={{ 'onboarding': 1 }}
    >
      <Component {...pageProps} />
    </DoptProvider>
  );
}
info

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:

pages/index.tsx
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.active}>
        <Modal.Overlay />
        <Modal.Content>
          <Modal.Header>
            <Modal.Title>{modal.title}</Modal.Title>
            <Modal.DismissIcon onClick={modal.dismiss} />
          </Modal.Header>
          <Modal.Body>{modal.body}</Modal.Body>
          <Modal.Footer>
            <Modal.DismissButton onClick={modal.dismiss}>
              {modal.dismissLabel}
            </Modal.DismissButton>
            <Modal.CompleteButton onClick={modal.complete}>
              {modal.completeLabel}
            </Modal.CompleteButton>
          </Modal.Footer>
        </Modal.Content>
      </Modal.Root>
    </>
  );
}
info

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:

pages/index.tsx
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={modal.active}>
        <h1>{modal.title}</h1>
        <RichText>{modal.body}</RichText>
        <button onClick={modal.dismiss}>{modal.dismissLabel}</button>
        <button onClick={modal.complete}>{modal.completeLabel}</button>
      </dialog>
    </>
  );
}

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 →