<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: {}`	Data	Required
`dnd`	`dnd: {}`	DndConfig	-
`children`	`children: <Puck.Preview />`	ReactNode	-
`headerPath`	`headerPath: "/my-page"`	String	-
`headerTitle`	`headerTitle: "My Page"`	String	-
`iframe`	`iframe: {}`	IframeConfig	-
`initialHistory`	`initialHistory: {}`	InitialHistory	-
`onAction()`	`onAction: (action, appState, prevAppState) => {}`	Function	-
`onChange()`	`onChange: (data) => {}`	Function	-
`onPublish()`	`onPublish: async (data) => {}`	Function	-
`overrides`	`overrides: { header: () => <div /> }`	Overrides	Experimental
`permissions`	`permissions: {}`	Plugin[]	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	-
`waitForStyles`	`waitForStyles: false`	boolean	-

`enabled`

Render the Puck preview within iframe. Defaults to true.

Disabling iframes will also disable viewports.

`waitForStyles`

Defer rendering of the Puck preview until the iframe styles have loaded, showing a spinner. Defaults to true.

`initialHistory`

Sets the undo/redo Puck history state when using the usePuck history API.

const historyState = {
  data: {
    root: {
      props: { title: "My History" },
    },
  },
};
 
export function Editor() {
  return (
    <Puck
      initialHistory={{
        histories: [{ state: historyState }],
        index: 0,
      }}
      // ...
    />
  );
}

`initialHistory` params

Param	Example	Type	Status
`histories`	`histories: []`	History[]	Required
`index`	`index: 2`	Number	Required
`appendData`	`appendData: false`	Boolean	-

`histories`

An array of histories to reset the Puck state history state to.

`index`

The index of the histories to set the user to.

`appendData`

Append the Puck data prop onto the end of histories. Defaults to true.

When false, the Puck data prop will be ignored but you must specify at least one item in the histories array.

`onAction(action, appState, prevAppState)`

Callback that triggers when Puck dispatches an action, like insert or set. Use this to track changes, perform side effects, or sync with external systems.

Receives three arguments:

action: The action that was dispatched
appState: The new AppState after the action was applied
prevAppState: The previous AppState before the action was applied

export function Editor() {
  return (
    <Puck
      onAction={(action, appState, prevAppState) => {
        if (action.type === "insert") {
          console.log("New component was inserted", appState);
        }
      }}
      // ...
    />
  );
}

`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 />,
      }}
      // ...
    />
  );
}

`permissions`

Set the global permissions for the Puck instance to toggle Puck functionality.

export function Editor() {
  return (
    <Puck
      permissions={{
        delete: false, // Prevent deletion of all components
      }}
      // ...
    />
  );
}

`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. You can use lucide-react 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"
  }
]

<Puck>

Props

Required props

config

data

Optional props

children

dnd

dnd params

disableAutoScroll

headerPath

headerTitle

iframe

iframe params

enabled

waitForStyles

initialHistory

initialHistory params

histories

index

appendData

onAction(action, appState, prevAppState)

onChange(data)

onPublish(data)

overrides

permissions

plugins

ui

viewports