<Puck>

Render the Puck editor.

import { Puck } from "@measured/puck";
 
const config = {
  components: {},
};
 
const initialData = {
  content: [],
  root: {},
};
 
export function Editor() {
  return <Puck config={config} data={initialData} />;
}

Props

Param	Example	Type	Status
`config`	`config: { components: {} }`	Config	Required
`data`	`data: { content: [], root: {} }`	Data	Required
`dnd`	`dnd: {}`	DndConfig	-
`children`	`children: <Puck.Preview />`	ReactNode	-
`headerPath`	`headerPath: "/my-page"`	String	-
`headerTitle`	`headerTitle: "My Page"`	String	-
`iframe`	`iframe: {}`	IframeConfig	-
`onChange()`	`onChange: (data) => {}`	Function	-
`onPublish()`	`onPublish: async (data) => {}`	Function	-
`overrides`	`overrides: { header: () => <div /> }`	Overrides	Experimental
`plugins`	`plugins: [myPlugin]`	Plugin[]	Experimental
`ui`	`ui: {leftSideBarVisible: false}`	AppState.ui	-
`viewports`	`viewports: [{ width: 1440 }]`	Viewport[]	-

Required props

`config`

An object describing the available components, fields and more. See the Config docs for a full reference.

export function Editor() {
  return (
    <Puck
      config={{
        components: {
          HeadingBlock: {
            fields: {
              children: {
                type: "text",
              },
            },
            render: ({ children }) => {
              return <h1>{children}</h1>;
            },
          },
        },
      }}
      // ...
    />
  );
}

`data`

The initial data to render. Cannot be changed once <Puck> has been mounted. See the Data docs for a full reference.

export function Editor() {
  return (
    <Puck
      data={{
        content: [
          {
            props: { children: "Hello, world", id: "id" },
            type: "HeadingBlock",
          },
        ],
        root: {},
      }}
      // ...
    />
  );
}

Optional props

`children`

Render custom nodes to create custom interfaces.

export function Editor() {
  return (
    <Puck /*...*/>
      <Puck.Preview />
    </Puck>
  );
}

`dnd`

Configure drag-and-drop behavior.

dnd params

Param	Example	Type	Status
`disableAutoScroll`	`disableAutoScroll: true`	boolean	-

`disableAutoScroll`

Disable auto-scroll when the user drags an item near the edge of the preview area.

`headerPath`

Set a path to show after the header title

export function Editor() {
  return (
    <Puck
      headerPath="/my-page"
      // ...
    />
  );
}

`headerTitle`

Set the title shown in the header

export function Editor() {
  return (
    <Puck
      headerPath="My page"
      // ...
    />
  );
}

`iframe`

Configure the iframe behaviour.

export function Editor() {
  return (
    <Puck
      iframe={{ enabled: false }}
      // ...
    />
  );
}

iframe params

Param	Example	Type	Status
`enabled`	`enabled: false`	boolean	-

`enabled`

Render the Puck preview within iframe. Defaults to true.

Disabling iframes will also disable viewports.

`onChange(data)`

Callback that triggers when the user makes a change.

Receives a single Data arg.

export function Editor() {
  return (
    <Puck
      onChange={(data) => {
        console.log("Puck data was updated", data);
      }}
      // ...
    />
  );
}

`onPublish(data)`

Callback that triggers when the user hits the "Publish" button. Use this to save the Puck data to your database.

Receives a single Data arg.

export function Editor() {
  return (
    <Puck
      onPublish={async (data) => {
        await fetch("/my-api", {
          method: "post",
          body: JSON.stringify({ data }),
        });
      }}
      // ...
    />
  );
}

`overrides`

An Overrides object defining custom render methods for various parts of the Puck UI.

export function Editor() {
  return (
    <Puck
      overrides={{
        header: () => <div />,
      }}
      // ...
    />
  );
}

`plugins`

An array of plugins to enhance Puck's behaviour. See the Plugin API reference.

import headingAnalyzer from "@measured/puck-plugin-heading-analyzer";
 
export function Editor() {
  return (
    <Puck
      plugins={[headingAnalyzer]}
      // ...
    />
  );
}

`ui`

Set the initial application UI state. See AppState.ui.

export function Editor() {
  return (
    <Puck
      // Hide the left side bar by default
      ui={{ leftSideBarVisible: false }}
      // ...
    />
  );
}

`viewports`

Configure the viewports available to the user, rendered as an iframe. Puck will select the most appropriate initial viewport based on the user's window size, unless otherwise specified via the ui prop.

export function Editor() {
  return (
    <Puck
      viewports={[
        {
          width: 1440,
        },
      ]}
      // ...
    />
  );
}

Viewport params

Param	Example	Type	Status
`width`	`width: 1440`	number	Required
`height`	`height: 968`	number \| `"auto"`	-
`icon`	`icon: "Monitor"`	`"Smartphone"` \| `"Tablet"` \| `"Monitor"` \| ReactNode	-
`label`	`label: "iPhone"`	string	-

`width`

The width of the viewport.

`height`

An optional height for the viewport. Defaults to auto, which will fit to the window.

`label`

An optional label for the viewport. This is used for browser tooltip.

`icon`

The icon to show in the viewport switcher. Can be:

"Smartphone"
"Tablet"
"Monitor"
ReactNode

Puck uses Lucide icons (opens in a new tab). You can use lucide-react (opens in a new tab) to choose a similar icon, if desired.

Default viewports

By default, Puck exposes small, medium and large viewports based on common viewport sizes.

[
  {
    "width": 360,
    "height": "auto",
    "icon": "Smartphone",
    "label": "Small"
  },
  {
    "width": 768,
    "height": "auto",
    "icon": "Tablet",
    "label": "Medium"
  },
  {
    "width": 1280,
    "height": "auto",
    "icon": "Monitor",
    "label": "Large"
  }
]