JavaScript SDK: React Library

Last Updated: May 8, 2024
documentation for the dotCMS Content Management System

The @dotcms/react library provides React components and hooks designed to work with dotCMS, making it easy to build pages and applications with ReactJS that are fully interoperable with the dotCMS Universal Visual Editor.


Installation can be performed via package manager. Choose any of the following commands:

npm install @dotcms/react

pnpm install @dotcms/react

yarn add @dotcms/react


DotcmsLayout Component

The central element of the React library is the DotcmsLayout component. It effectively mirrors the data structure of the template or layout of a dotCMS page — subdividing into rows, columns, and containers. See Templating for more information.

The DotcmsLayout component creates a global React context with response data from the Page API, referred to in the library as PageProviderContext.

DotcmsLayout accepts two data properties:

entityAn object containing the context data for the page. This corresponds to the entity property returned by a Page API call, such as via the client library's {client}.page.get() method.
DotcmsLayout additionally looks for the definition of a components child property within entity, described below.
configOptional. An object with two properties:
  • onReload: Optional. A callback function to be called when the page editor needs to reload the page.
  • pathname: Optional. The path portion of the URL of the page being edited.

An example usage of DotcmsLayout might look like this:

import { DotcmsLayout } from '@dotcms/react';

const MyPage = ({ entity }) => {
    return <DotcmsLayout entity={entity} />;

Entity Object

The entity object delivers all relevant page data the DotcmsLayout component for rendering.

Within entity, a components property accepts a map of components to Content Types, the basic data structures of dotCMS. Each key is the Content Type variable and the value is the name of a React component; that is, each Content Type's rendering behavior will be controlled by its corresponding React component.

list of components.

If the data from the client's .page.get() call were passed by the name data, a DotcmsLayout can include both the component map and the Page API response entity through use of the spread operator on the latter, as below:

        components: {
            webPageContent: WebPageContent,
            Banner: Banner,
            Activity: Activity,
            Product: Product,
            Image: ImageComponent,

For a more elaborate treatment, see the my-page.js component in the Universal Visual Editor's NextJS example, which implements the React library.

useDotcmsPageContext Hook

The useDotcmsPageContext hook allows a component to access the global context that contains the Page API object response.

import { useDotcmsPageContext } from '@dotcms/react';

const MyComponent = () => {
    const context = useDotcmsPageContext();
    // Use the context

For more elaborate examples, see the Content Type components in the NextJS example.

On this page


We Dig Feedback

Selected excerpt: