Docs
API Reference
Components
<Puck>

<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

ParamExampleTypeStatus
configconfig: { components: {} }ConfigRequired
datadata: {}DataRequired
dnddnd: {}DndConfig-
childrenchildren: <Puck.Preview />ReactNode-
headerPathheaderPath: "/my-page"String-
headerTitleheaderTitle: "My Page"String-
iframeiframe: {}IframeConfig-
initialHistoryinitialHistory: {}InitialHistory-
onAction()onAction: (action, appState, prevAppState) => {}Function-
onChange()onChange: (data) => {}Function-
onPublish()onPublish: async (data) => {}Function-
overridesoverrides: { header: () => <div /> }OverridesExperimental
permissionspermissions: {}Plugin[]Experimental
pluginsplugins: [myPlugin]Plugin[]Experimental
uiui: {leftSideBarVisible: false}AppState.ui-
viewportsviewports: [{ 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

ParamExampleTypeStatus
disableAutoScrolldisableAutoScroll: trueboolean-
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

ParamExampleTypeStatus
enabledenabled: falseboolean-
waitForStyleswaitForStyles: falseboolean-
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

ParamExampleTypeStatus
historieshistories: []History[]Required
indexindex: 2NumberRequired
appendDataappendData: falseBoolean-
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 (opens in a new tab), like insert or set. Use this to track changes, perform side effects, or sync with external systems.

Receives three arguments:

  1. action: The action that was dispatched
  2. appState: The new AppState after the action was applied
  3. 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

ParamExampleTypeStatus
widthwidth: 1440numberRequired
heightheight: 968number | "auto"-
iconicon: "Monitor""Smartphone" | "Tablet" | "Monitor" | ReactNode-
labellabel: "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"
  }
]
<FieldLabel><Puck.Components>