Puck

https://puckeditor.com/docs
Admin
Puck is a modular, open-source visual editor for React.js, enabling custom drag-and-drop experiences...
Tokens:148,038
Snippets:1,593
Trust Score:7.1
Update:3 days ago
Show doc for...
Tokens:
Raw
### Prompt Agent for Setup

Source: https://puckeditor.com/docs/ai/getting-started

Prompt the agent to create a Puck AI application after installing the skill.

```text
Use the Puck skill to create a Puck AI application.
```

--------------------------------

### Zone parameter example

Source: https://puckeditor.com/docs/api-reference/data-model/item-selector

Example usage of the zone parameter.

```text
zone: "Flex-123:children" }
```

--------------------------------

### Index parameter example

Source: https://puckeditor.com/docs/api-reference/data-model/item-selector

Example usage of the index parameter.

```text
index: 0
```

--------------------------------

### Define example prompts

Source: https://puckeditor.com/docs/api-reference/ai/ai-plugin/create-ai-plugin

Sets example prompts to display beneath the text input using chat.examplePrompts.

```ts
const aiPlugin = createAiPlugin({
  chat: {
    examplePrompts: [
      { label: "Landing page", href: "/?prompt=Create+a+landing+page" },
      { label: "Click handler", onClick: () => console.log("clicked") },
    ],
  },
});
```

--------------------------------

### Install Cloud Client via npm

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/installation

Use this command to install the @puckeditor/cloud-client package into your project.

```sh
npm i @puckeditor/cloud-client --save
```

--------------------------------

### Install @puckeditor/core via npm

Source: https://puckeditor.com/docs/getting-started

Install the core package using npm.

```sh
npm i @puckeditor/core --save
```

--------------------------------

### content parameter example

Source: https://puckeditor.com/docs/api-reference/data-model/data

Example showing the content array with a single HeadingBlock component instance.

```json
{
  "content": [
    {
      "type": "HeadingBlock",
      "props": {
        "id": "HeadingBlock-1234",
        "title": "Hello, world"
      }
    }
  ],
  "root": {},
  "zones": {}
}
```

--------------------------------

### puckHandler - Tanstack Start Integration

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler

Example of using puckHandler in a Tanstack Start application to handle GET, POST, and DELETE requests for the /api/puck/* path.

```APIDOC
## puckHandler - Tanstack Start Integration

### Description
Handle all endpoints for the /api/puck/* path in a Tanstack Start application. The puckHandler function is called with the request and an options object containing an ai.context string to fine-tune AI behavior.

### Method
GET, POST, DELETE

### Endpoint
/api/puck/*

### Parameters
#### Request
- **request** (Request) - Required - The incoming HTTP request object.
- **options** (object) - Optional - Configuration object.
  - **ai** (object) - Optional - AI configuration.
    - **context** (string) - Optional - Context string for AI behavior.

### Request Example
```ts
// routes/api/puck.$.ts

const handleRequest = (ctx) => {
  return puckHandler(ctx.request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

export const APIRoute = createAPIFileRoute("/api/puck/$")({
  DELETE: handleRequest,
  GET: handleRequest,
  POST: handleRequest,
});
```

### Response
Returns the response from the puckHandler function, which handles the request and returns an appropriate response.
```

--------------------------------

### <ActionBar.Label> usage example

Source: https://puckeditor.com/docs/api-reference/components/action-bar-label

Example showing how to use <ActionBar.Label> inside an <ActionBar> and an <ActionBar.Group>.

```APIDOC
## <ActionBar.Label>

### Description
Renders a label in the <ActionBar> or an <ActionBar.Group>.

### Usage Example
```tsx
<ActionBar>
  <ActionBar.Label label="Label 1" />
  <ActionBar.Group>
    <ActionBar.Label label="Label 2" />
    <ActionBar.Action>★</ActionBar.Action>
  </ActionBar.Group>
</ActionBar>
```

### Props

| Prop | Type | Status |
|------|------|--------|
| label | String | Required |

### Required Props

#### label
The label text.
```

--------------------------------

### root parameter example

Source: https://puckeditor.com/docs/api-reference/data-model/data

Example showing the root object with props containing a title.

```json
{
  "content": [],
  "root": {
    "props": {
      "title": "My page"
    }
  },
  "zones": {}
}
```

--------------------------------

### Example only updating the permissions when 'example' prop changes

Source: https://puckeditor.com/docs/api-reference/configuration/component-config

Shows how to use the changed parameter to optimize performance by only performing expensive asynchronous operations when specific props are modified.

```tsx
const resolvePermissions = async ({ props }, { changed, lastPermissions }) => {
  if (!changed.example) {
    return lastPermissions; // Return the last permissions unless the `example` prop has changed
  }

  return await expensiveAsyncOperation();
};
```

--------------------------------

### Configure Tanstack Start Backend

Source: https://puckeditor.com/docs/ai/getting-started

Mount the puckHandler in a Tanstack Start API route file.

```ts
// routes/api/puck.$.ts


const handleRequest = (ctx) => {
  return puckHandler(ctx.request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

export const APIRoute = createAPIFileRoute("/api/puck/$")({
  DELETE: handleRequest,
  GET: handleRequest,
  POST: handleRequest,
});
```

--------------------------------

### zones parameter example

Source: https://puckeditor.com/docs/api-reference/data-model/data

Example showing the zones object with a DropZone keyed by component id and zone name.

```json
{
  "content": [],
  "root": {},
  "zones": {
    "HeadingBlock-1234:my-content": [
      {
        "type": "HeadingBlock",
        "props": {
          "id": "HeadingBlock-1234",
          "title": "Hello, world"
        }
      }
    ]
  }
}
```

--------------------------------

### walkTree usage example

Source: https://puckeditor.com/docs/api-reference/functions/walk-tree

Demonstrates using walkTree to inject an example prop into all children within the data structure.

```tsx
// Add the example prop to all children in the data
const newData = walkTree(data, config, (content) =>
  content.map((child) => ({
    ...child,
    props: { ...child.props, example: "Hello, world" },
  }))
);

console.log(newData);
// {
//   "root": {},
//   "content": [
//     {
//       "type": "Component",
//       "props": {
//         "id": "1234",
//         "content": [
//           {
//             "type": "Child",
//             "props": { "id": "5678", "example": "Hello, world" }
//           }
//         ],
//         "example": "Hello, world"
//       }
//     }
//   ]
// }
```

--------------------------------

### Full Data object example

Source: https://puckeditor.com/docs/api-reference/data-model/data

Complete example of a Puck Data object with content, root, and zones properties.

```json
{
  "content": [
    {
      "type": "HeadingBlock",
      "props": {
        "id": "HeadingBlock-1234",
        "title": "Hello, world"
      }
    }
  ],
  "root": { "props": { "title": "Puck Example" } },
  "zones": {}
}
```

--------------------------------

### ActionBar preview example

Source: https://puckeditor.com/docs/api-reference/components/action-bar

An example of the ActionBar component rendered within a flex container for preview purposes.

```tsx
<PuckPreview>
  <div style={{ display: "flex" }}>
    <ActionBar label="Actions">
      <ActionBar.Group>
        <ActionBar.Action>★</ActionBar.Action>
      </ActionBar.Group>
    </ActionBar>
  </div>
</PuckPreview>
```

--------------------------------

### ConfigPreview component configuration

Source: https://puckeditor.com/docs/api-reference/configuration/component-config

An interactive configuration example showing how to define fields and resolveData for a component.

```tsx
<ConfigPreview
  label='Try changing the "title" field'
  componentConfig={{
    fields: {
      title: {
        type: "text",
      },
      resolvedTitle: {
        type: "text",
      },
    },
    defaultProps: {
      title: "Hello, world",
    },
    resolveData: ({ props }) => {
      return {
        props: { resolvedTitle: props.title },
        readOnly: { resolvedTitle: true },
      };
    },
    render: ({ resolvedTitle }) => {
      return <p style={{ margin: 0 }}>{resolvedTitle}</p>;
    },

}}
```

--------------------------------

### ActionBar.Action usage example

Source: https://puckeditor.com/docs/api-reference/components/action-bar-action

Example of using ActionBar.Action inside an ActionBar with an onClick handler.

```APIDOC
## ActionBar.Action

### Description
Renders an action button inside an ActionBar. Often used inside an ActionBar.Group.

### Usage Example
```tsx
<ActionBar>
  <ActionBar.Action onClick={() => console.log("Clicked!")}>★</ActionBar.Action>
</ActionBar>
```

### Props

| Prop | Example | Type | Status |
| --- | --- | --- | --- |
| children | <svg /> | ReactNode | Required |
| onClick | () => void | Function | Optional |
| label | "Label" | String | Optional |

#### Required Props

- **children** (ReactNode) - Required - A node to render as the children of the action. Should be a string or an icon.

#### Optional Props

- **onClick(e)** (Function) - Optional - An onClick callback triggered when the user clicks the action.
- **label** (String) - Optional - A label to provide an accessible label when using icon.
```

--------------------------------

### Install Puck Skill

Source: https://puckeditor.com/docs/ai/getting-started

Use the Puck skill to set up a Puck AI application.

```sh
npx skills add https://github.com/puckeditor/skills --skill puck
```

--------------------------------

### Puck.Outline usage example

Source: https://puckeditor.com/docs/api-reference/components/puck-outline

An example showing how to include the Puck.Outline component within a Puck editor structure.

```tsx
export function Editor() {
  return (
    <Puck>
      <Puck.Outline />
    </Puck>
  );
}
```

--------------------------------

### Install AI Plugin via npm or yarn

Source: https://puckeditor.com/docs/api-reference/ai/ai-plugin/installation

Use this command to install the AI plugin package into your project.

```sh
npm i @puckeditor/plugin-ai --save
```

--------------------------------

### ConfigPreview for contentEditable

Source: https://puckeditor.com/docs/api-reference/fields/custom

A live preview example demonstrating a custom field with contentEditable enabled.

```tsx
<ConfigPreview
  label="Example"
  componentConfig={{
    fields: {
      title: {
        type: "custom",
        contentEditable: true,
        render: ({ name, onChange, value }) => (
          <input
            value={value}
            name={name}
            onChange={(e) => onChange(e.currentTarget.value)}
            style={{
              background: "white",
              border: "1px solid black",
              padding: 4,
            }}
          />
        ),
      },
    },
    defaultProps: {
      title: "Edit me inline",
    },
    render: ({ title }) => {
      return <div>{title}</div>;
    },
  }}
>
  <Puck.Preview />
</ConfigPreview>
```

--------------------------------

### Basic <Render> usage

Source: https://puckeditor.com/docs/api-reference/components/render

A basic example showing how to pass the required config and data props to the <Render> component.

```tsx
export function Example() {
  return <Render config={config} data={data} />;
}
```

--------------------------------

### Radio field configuration example

Source: https://puckeditor.com/docs/api-reference/fields/radio

A complete configuration example showing how to define a radio field within a component's fields object.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        textAlign: {
          type: "radio",
          options: [
            { label: "Left", value: "left" },
            { label: "Right", value: "right" },
          ],
        },
      },
      defaultProps: {
        textAlign: "left",
      },
      render: ({ textAlign }) => {
        return <p style={{ textAlign }}>Hello, world</p>;
      },
    },
  },
};
```

--------------------------------

### Component configuration parameters

Source: https://puckeditor.com/docs/api-reference/configuration/component-config

Examples of various configuration parameters used within a component definition.

```typescript
render: () => <div />
```

```typescript
fields: { title: { type: "text"} }
```

```typescript
defaultProps: { title: "Hello, world" }
```

```typescript
inline: true
```

```typescript
label: "Heading Block"
```

```typescript
metadata: {}
```

```typescript
permissions: { delete: false }
```

```typescript
resolveData: async ({ props }) => ({ props })
```

```typescript
resolveFields: async ({ props }) => ({})
```

```typescript
resolvePermissions: async ({ props }) => ({})
```

--------------------------------

### Custom field configuration example

Source: https://puckeditor.com/docs/api-reference/fields/custom

This example demonstrates how to define a custom field within a component configuration, using a standard HTML input element to manage the field value.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        title: {
          type: "custom",
          render: ({ name, onChange, value }) => (
            <input
              defaultValue={value}
              name={name}
              onChange={(e) => onChange(e.currentTarget.value)}
            />
          ),
        },
      },
      render: ({ title }) => {
        return <p>{title}</p>;
      },
    },
  },
};
```

--------------------------------

### <Drawer.Item> Basic Usage

Source: https://puckeditor.com/docs/api-reference/components/drawer-item

Example of using <Drawer.Item> with a name prop inside a <Drawer>.

```APIDOC
## <Drawer.Item> Basic Usage

### Description
Renders a draggable item with the given name inside a <Drawer>.

### Component
<Drawer.Item>

### Props
#### Required Props
- **name** (String) - Required - The name of the drawer item. This will be rendered on the item by default and used as the id unless otherwise specified.

#### Optional Props
- **children** (Function) - Optional - A custom render function to render inside the component. Receives render props.
- **id** (String) - Optional - A unique id for this drawer item. Defaults to the value of name.
- **isDragDisabled** (Boolean) - Optional - Whether or not this item is disabled.

### Example
```tsx
import { Puck, Drawer } from "@measured/puck";

export function Editor() {
  return (
    <Puck>
      <Drawer>
        <Drawer.Item name="Orange" />
      </Drawer>
    </Puck>
  );
}
```
```

--------------------------------

### Define a component configuration

Source: https://puckeditor.com/docs/api-reference/configuration/component-config

Example of a component configuration object including fields and a render function.

```tsx
const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
        },
      },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};
```

--------------------------------

### PuckPreview for Tabs example

Source: https://puckeditor.com/docs/integrating-puck/overlay-portals

A PuckPreview component demonstrating the use of Overlay Portals to create interactive tabs.

```tsx
<PuckPreview
  label="Tabs example"
  config={{
    components: {
      Example: {
        render: () => {
          return <OverlayPortalTabsPreview />;
        },
      },
    },
  }}
  data={{
    content: [
      {
        type: "Example",
        props: {
          id: "Example-1",
        },
      },
    ],
    root: { props: {} },
  }}
>
  <Puck.Preview />
</PuckPreview>
```

--------------------------------

### Configure instructions on fields

Source: https://puckeditor.com/docs/ai/ai-configuration

Apply the instructions parameter to specific fields to guide the agent's behavior for that field.

```ts
const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
          ai: {
            instructions: "Always use caps",
          },
        },
      },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};
```

--------------------------------

### ConfigPreview for key remounting

Source: https://puckeditor.com/docs/api-reference/fields/custom

A live preview example showing how to use the key parameter to switch between different field types dynamically.

```tsx
<ConfigPreview
  label="Example"
  componentConfig={{
    fields: {
      isText: {
        type: "radio",
        options: [
          { label: "Yes", value: true },
          { label: "No", value: false },
        ],
      },
    },
    resolveFields: (data, params) => {
      if (data.props.isText) {
        return {
          ...params.fields,
          title: {
            type: "custom",
            key: "custom-text",
            render: ({ onChange, value }) => (
              <FieldLabel label="Text Input">
                  <AutoField
                    field={{ type: "text" }}
                    value={value}
                    onChange={onChange}
                  />
              </FieldLabel>
            ),
          },
        };
      } else {
        return {
          ...params.fields,
          title: {
            type: "custom",
            key: "custom-number",
            render: ({ value, onChange }) => {
              return (
                <FieldLabel label="Number Input">
                  <AutoField
                    field={{ type: "number" }}
                    value={value}
                    onChange={onChange}
                  />
                </FieldLabel>
              );
            },
          },
        };
      }
    },
    resolveData: (data, params) => {
      if (!params.changed.isText) return data;

      if (data.props.isText) {
        return {
          ...data,
          props: {
            ...data.props,
            title: "Title",
          },
        };
      } else {
        return {
          ...data,
          props: {
            ...data.props,
            title: 123,
          },
        };
      }
    },
    defaultProps: {
      isText: true,
    },
    render: ({ title }) => {
      return <p style={{color: "black"}}>{title}</p>;
    },

}}

>

  <Puck.Preview />
</ConfigPreview>
```

--------------------------------

### puckHandler - Next.js Integration

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler

Example of using puckHandler in a Next.js API route to handle GET, POST, and DELETE requests for the /api/puck/* path.

```APIDOC
## puckHandler - Next.js Integration

### Description
Handle all endpoints for the /api/puck/* path in a Next.js application. The puckHandler function is called with the request and an options object containing an ai.context string to fine-tune AI behavior.

### Method
GET, POST, DELETE

### Endpoint
/api/puck/*

### Parameters
#### Request
- **request** (Request) - Required - The incoming HTTP request object.
- **options** (object) - Optional - Configuration object.
  - **ai** (object) - Optional - AI configuration.
    - **context** (string) - Optional - Context string for AI behavior.

### Request Example
```ts
// app/api/puck/[...all]/route.ts

const handleRequest = (request) => {
  return puckHandler(request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

export const DELETE = handleRequest;
export const GET = handleRequest;
export const POST = handleRequest;
```

### Response
Returns the response from the puckHandler function, which handles the request and returns an appropriate response.
```

--------------------------------

### puckHandler - React Router Integration

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler

Example of using puckHandler in a React Router application, where the loader handles GET and the action handles POST and DELETE for the /api/puck/* route.

```APIDOC
## puckHandler - React Router Integration

### Description
Handle all endpoints for the /api/puck/* path in a React Router application. The puckHandler function is called with the request and an options object containing an ai.context string to fine-tune AI behavior.

### Method
GET (loader), POST and DELETE (action)

### Endpoint
/api/puck/*

### Parameters
#### Request
- **request** (Request) - Required - The incoming HTTP request object.
- **options** (object) - Optional - Configuration object.
  - **ai** (object) - Optional - AI configuration.
    - **context** (string) - Optional - Context string for AI behavior.

### Request Example
```ts
// app/routes/api.puck.ts

const handleRequest = (args) => {
  return puckHandler(args.request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

// loader handles GET, action handles POST and DELETE
export const loader = handleRequest;
export const action = handleRequest;

// /app/routes.ts

  index("routes/home.tsx"),
  route("api/puck/*", "routes/api.puck.tsx"),
] satisfies RouteConfig;
```

### Response
Returns the response from the puckHandler function, which handles the request and returns an appropriate response.
```

--------------------------------

### Initialize usePuck with createUsePuck

Source: https://puckeditor.com/docs/api-reference/functions/use-puck

The recommended way to access usePuck is by using the createUsePuck factory to enable selector support.

```tsx
const usePuck = createUsePuck();

const Example = () => {
  const type = usePuck((s) => s.selectedItem?.type || "Nothing");

  return <h2>{type} selected</h2>;
};
```

--------------------------------

### Configure AI instructions for a component

Source: https://puckeditor.com/docs/api-reference/ai/configuration/components

Sets the instructions property within the ai config of a component. The instructions string guides the AI when considering this component. This example shows a HeadingBlock component with instructions to always place it first.

```tsx
const config = {
  components: {
    HeadingBlock: {
      ai: {
        instructions: "Always place this first",
      },
      fields: {
        title: {
          type: "text",
        },
      },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};
```

--------------------------------

### Implement a fixed layout with PuckPreview

Source: https://puckeditor.com/docs/integrating-puck/multi-column-layouts

This example demonstrates a complete Puck configuration with a root DropZone and a custom multi-column component, including initial data structure.

```tsx
<PuckPreview
  label="Fixed layout example"
  config={{
    root: {
      render: ({ puck: { renderDropZone: DropZone } }) => (
        <DropZone zone="default-zone" disallow={["Card"]} />
      ),
    },
    components: {
      Example: {
        fields: {
          leftColumn: {
            type: "slot",
          },
          rightColumn: {
            type: "slot",
          },
        },
        render: ({ leftColumn: LeftColumn, rightColumn: RightColumn }) => {
          return (
            <div
              style={{
                display: "grid",
                gridTemplateColumns: "1fr 1fr",
                gap: 16,
              }}
            >
              <LeftColumn />
              <RightColumn />
            </div>
          );
        },
      },
      Card: {
        render: ({ content }) => {
          return (
            <div
              style={{
                background: "white",
                border: "1px solid black",
                borderRadius: 4,
                padding: 16,
              }}
            >
              {content}
            </div>
          );
        },
      },
    },
  }}
  data={{
    content: [
      {
        type: "Example",
        props: {
          id: "Example-1",
          leftColumn: [
            {
              type: "Card",
              props: { id: "Example-2", content: "1" },
            },
          ],
          rightColumn: [
            {
              type: "Card",
              props: { id: "Example-3", content: "2" },
            },
          ],
        },
      },
    ],
    root: { props: {} },
  }}
>
  <Puck.Preview />
</PuckPreview>
```

--------------------------------

### Initialize and use createAiPlugin

Source: https://puckeditor.com/docs/api-reference/ai/ai-plugin/create-ai-plugin

Shows how to instantiate the AI plugin and include it in the Puck editor's plugins array.

```jsx
const aiPlugin = createAiPlugin();

export function Editor() {
  return (
    <Puck
      plugins={[aiPlugin]}
      // ...
    />
  );
}
```

--------------------------------

### fieldTypes override example

Source: https://puckeditor.com/docs/api-reference/overrides/field-types

Example of overriding field types with custom render methods.

```APIDOC
## fieldTypes

### Description
Override each field type by specifying a custom render method for each known field type, or introduce completely new ones.

### Usage
```tsx copy
const overrides = {
  fieldTypes: {
    number: ({ onChange }) => (
      <input type="number" onChange={(e) => onChange(e.currentTarget.value)} />
    ),
    text: ({ onChange }) => (
      <input type="text" onChange={(e) => onChange(e.currentTarget.value)} />
    ),
    // ...
  },
};
```

### Render Props
Extends the [`<AutoField>` API](/docs/api-reference/components/auto-field).

| Prop                    | Example     | Type                                                           |
| ----------------------- | ----------- | -------------------------------------------------------------- |
| [`children`](#children) | `<input />` | ReactNode                                                      |
| [`name`](#name)         | `"title"`   | string                                                         |
| `...`                   | `{}`        | [`<AutoField>` API](/docs/api-reference/components/auto-field) |

#### `children`
The default node for this field type.

#### `name`
The name of the prop this field is rendering for.
```

--------------------------------

### ConfigPreview implementation for showSearch

Source: https://puckeditor.com/docs/api-reference/fields/external

A complete configuration example demonstrating the use of showSearch with a filtering logic inside fetchList and a render function.

```tsx
{
  fields: {
    data: {
      type: "external",
      fetchList: async ({ query }) => {
        return [
          {
            title: "Apple",
            description:
              "An apple is a round, edible fruit produced by an apple tree.",
          },
          {
            title: "Orange",
            description:
              "An orange is a fruit of various citrus species in the family Rutaceae.",
          },
        ].filter((item) => {
          if (!query) return item;

          const queryLowercase = query.toLowerCase();

          if (item.title.toLowerCase().indexOf(queryLowercase) > -1) {
            return item;
          }

          if (item.description.toLowerCase().indexOf(queryLowercase) > -1) {
            return item;
          }
        })
      },
      showSearch: true,
    },
  },
  render: ({ data }) => {
    return <p>{data?.title || "No data selected"}</p>;
  },
}
```

--------------------------------

### ActionBar.Group usage example

Source: https://puckeditor.com/docs/api-reference/components/action-bar-group

Example of using ActionBar.Group inside an ActionBar to render action groups.

```APIDOC
## ActionBar.Group

### Description
Renders an action group in the ActionBar. Use ActionBar.Separator instead to avoid wrapping elements.

### Usage Example
```tsx
<ActionBar label="Actions">
  <ActionBar.Group>Group 1</ActionBar.Group>
  <ActionBar.Group>Group 2</ActionBar.Group>
</ActionBar>
```

### Props

| Prop | Example | Type | Status |
| --- | --- | --- | --- |
| children | <div /> | ReactNode | Required |

### Required Props

#### children
A node to render as the children of the action. If a fragment, the items will be rendered in a flex row. Normally contains ActionBar.Action.
```

--------------------------------

### Basic Drawer usage

Source: https://puckeditor.com/docs/api-reference/components/drawer

Shows how to implement a Drawer component within a Puck editor instance.

```tsx
export function Editor() {
  return (
    <Puck>
      <Drawer>
        <Drawer.Item name="Orange" />
      </Drawer>
    </Puck>
  );
}
```

--------------------------------

### generate() with tools

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/generate

Example of calling generate() with tools to define functions the agent can execute on the server to retrieve data, which is factored into the request.

```APIDOC
## generate() with tools

### Description
Define tools that enable the agent to execute functions on your server and retrieve data. The result of the tool will be factored into the request.

### Method
Function call: generate()

### Parameters
#### tools
- **getProducts** (object) - Required - A tool definition with a description, input schema, and execute function.
  - **description** (string) - Required - Description of the tool.
  - **inputSchema** (object) - Required - Zod schema for the tool input.
  - **execute** (function) - Required - Async function that executes the tool and returns data.

### Request Example
```tsx
const page = await generate({
  prompt: "Create a page about our products",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  tools: {
    getProducts: tool({
      description: "Get a list of product codes",
      inputSchema: z.object(),
      execute: async () => {
        return [
          {
            name: "Google Maps",
            product_code: "maps",
          },
          {
            name: "Google Calendar",
            product_code: "calendar",
          },
        ];
      },
    }),
  },
});
```
```

--------------------------------

### Configure asynchronous fields with ConfigPreview

Source: https://puckeditor.com/docs/integrating-puck/dynamic-fields

A live preview configuration demonstrating asynchronous option loading for a select field based on a category radio selection.

```tsx
<ConfigPreview
  label='Try changing the "category" field'
  componentConfig={{
    resolveFields: async (data, { changed, lastFields }) => {
      if (!changed.category) return lastFields;

      await new Promise((resolve) => setTimeout(resolve, 500));

      return {
        category: {
          type: "radio",
          options: [
            { label: "Fruit", value: "fruit" },
            { label: "Vegetables", value: "vegetables" },
          ],
        },
        item: {
          type: "select",
          options:
            data.props.category === "fruit"
              ? [
                { label: "Select a fruit", value: "" },
                { label: "Apple", value: "apple" },
                { label: "Orange", value: "orange" },
                { label: "Tomato", value: "tomato" }
              ] : [
                { label: "Select a vegetable", value: "" },
                { label: "Broccoli", value: "broccoli" },
                { label: "Cauliflower", value: "cauliflower" },
                { label: "Mushroom", value: "mushroom" },
              ],
        },
      };
    },

    defaultProps: {
      category: "fruit",
      item: "",
    },
    render: ({ item }) => <p>{item}</p>,

}}
/>
```

--------------------------------

### CSS example for button theming

Source: https://puckeditor.com/docs/api-reference/theming/button

Use these CSS custom properties to customize the button radius and primary colors. The example sets a pill-shaped radius and purple background colors.

```css
.Container {
  --puck-button-radius: 9999px;
  --puck-button-primary-color-bg: #6d28d9;
  --puck-button-primary-color-bg-hover: #5b21b6;
}
```

--------------------------------

### generate() with context parameter

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/generate

Shows how to provide system context and instructions to the agent via the 'context' parameter.

```tsx
const page = await generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  context: "We are Google. Your job is to create Google landing pages.",
});
```

--------------------------------

### getItemBySelector(selector)

Source: https://puckeditor.com/docs/api-reference/puck-api

Gets an item's ComponentData by its selector.

```APIDOC
## getItemBySelector(selector)

### Description
Gets an item's ComponentData by its selector.

### Parameters
- **selector** (ItemSelector) - Required - The selector of the item.

### Returns
ComponentData

### Example
```tsx
getItemBySelector({
  index: 0,
  zone: "Flex-123:children", // The "children" slot field in the component with id "Flex-123"
});
// { type: "HeadingBlock", props: {} }
```
```

--------------------------------

### tool() - Basic Configuration

Source: https://puckeditor.com/docs/ai/tools

Configures a tool with a description, input schema, and execute function. The tool is provided to puckHandler() or generate() APIs.

```APIDOC
## tool() - Basic Configuration

### Description
Configures a tool with a description, input schema, and execute function. The tool is provided to puckHandler() or generate() APIs.

### Method
N/A (SDK function)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **description** (string) - Required - Description of the tool for Puck AI to understand when to use it.
- **inputSchema** (Zod schema) - Required - Describes the shape of the args the AI will provide to the execute function.
- **execute** (function) - Required - Function called on your server. Receives args from the AI and returns a value.
- **mode** (string) - Optional - Execution mode: "auto" (use in either inline or preload modes), "preload" (default), or "inline".

### Request Example
```tsx
export async function POST(request) {
  return puckHandler(request, {
    ai: {
      tools: {
        getImageUrl: tool({
          description: "Get an image",
          inputSchema: z.object(), // No arguments needed
          execute: () => "https://www.example.com/example.png", // Call a function on your server
          mode: "auto", // Use in either inline or preload modes
        }),
      },
    },
  });
}
```

### Response
No response body. The tool's return value is provided to the agent.
```

--------------------------------

### getSelectorForId(id)

Source: https://puckeditor.com/docs/api-reference/puck-api

Gets an item's selector by its component id.

```APIDOC
## getSelectorForId(id)

### Description
Gets an item's selector by its component id.

### Parameters
- **id** (string) - Required - The component id.

### Returns
ItemSelector

### Example
```tsx
getSelectorForId("HeadingBlock-123");
// { index: 0, zone: "Flex-123:children" }
```
```

--------------------------------

### Generate a page with the generate function

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/generate

This example demonstrates how to use the generate function with a prompt and a component configuration to produce a Puck Data object.

```tsx
const page = await generate({
  prompt: "Create a page about dogs",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
});
// { root: { props: { title: "Pawesome Friends" } }, content: [ { type: "HeadingBlock", props: { id: "Heading-12345", title: "Discover Man's Best Friend" } } ] }
```

--------------------------------

### getItemById(id)

Source: https://puckeditor.com/docs/api-reference/puck-api

Gets an item's ComponentData by its component id.

```APIDOC
## getItemById(id)

### Description
Gets an item's ComponentData by its component id.

### Parameters
- **id** (string) - Required - The component id.

### Returns
ComponentData

### Example
```tsx
getItemById("HeadingBlock-123");
// { type: "HeadingBlock", props: {} }
```
```

--------------------------------

### Configure dynamic fields with ConfigPreview

Source: https://puckeditor.com/docs/integrating-puck/dynamic-fields

A live preview configuration showing how to toggle the availability of a 'waterType' field based on the 'drink' selection.

```tsx
<ConfigPreview
  label='Try changing the "drink" field'
  componentConfig={{
    resolveFields: (data) => {
      const fields = {
        drink: {
          type: "radio",
          options: [
            { label: "Water", value: "water" },
            { label: "Orange juice", value: "orange-juice" },
          ],
        },
      };

      if (data.props.drink === "water") {
        return {
          ...fields,
          waterType: {
            type: "radio",
            options: [
              { label: "Still", value: "still" },
              { label: "Sparkling", value: "sparkling" },
            ],
          },
        };
      }

      return fields;
    },
    defaultProps: {
      drink: "water",
      waterType: "still",
    },
    render: ({ drink, waterType }) => (
      <p>
        {drink}
        {drink === "water" ? ` (${waterType})` : ""}
      </p>
    ),

}}
/>
```

--------------------------------

### Override component overlay

Source: https://puckeditor.com/docs/api-reference/overrides/component-overlay

Example of defining the overlay override within the overrides object.

```tsx
const overrides = {
  overlay: ({ children }) => <div>{children}</div>,
};
```

--------------------------------

### ai.providerOptions

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/chat

Pass configuration options through to the model call. Options include openai.reasoningEffort, openai.serviceTier, and openai.textVerbosity.

```APIDOC
## ai.providerOptions

### Description
Pass configuration options through to the model call.

### Parameters
#### Provider Options
- **openai.reasoningEffort** (string) - Optional - The reasoning effort level. Allowed values: "none" | "minimal" | "low" | "medium" | "high" | "xhigh". Example: "low".
- **openai.serviceTier** (string) - Optional - The service tier. Allowed values: "auto" | "default" | "flex" | "priority". Example: "priority".
- **openai.textVerbosity** (string) - Optional - The text verbosity level. Allowed values: "low" | "medium" | "high". Example: "low".

### Request Example
```tsx
export async function POST(request) {
  const body = await request.json();

  return chat(body, {
    ai: {
      providerOptions: {
        openai: {
          serviceTier: "priority", // Enable faster responses
        },
      },
    },
  });
}
```
```

--------------------------------

### RootData basic structure

Source: https://puckeditor.com/docs/api-reference/data-model/root-data

A basic example of the RootData object containing a props object.

```json
{
  "props": {
    "title": "Hello, world"
  }
}
```

--------------------------------

### Load a plugin with the plugins prop

Source: https://puckeditor.com/docs/extending-puck/plugins

Provide the plugin to the plugins prop on the Puck component to load it. The example shows a minimal Editor component with a placeholder for the plugin.

```tsx
export function Editor() {
  return (
    <Puck
      // ...
      plugins={[myPlugin]}
    />
  );
}
```

--------------------------------

### ItemSelector JSON structure

Source: https://puckeditor.com/docs/api-reference/data-model/item-selector

An example of the ItemSelector object showing the index and zone properties.

```json
{
  "index": 0,
  "zone": "Flex-123:children" // The "children" slot field in the component with id "Flex-123"
}
```

--------------------------------

### generate() with providerOptions

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/generate

Example of calling generate() with providerOptions to pass configuration options to the model call, such as setting the OpenAI service tier to 'priority' for faster responses.

```APIDOC
## generate() with providerOptions

### Description
Pass configuration options through to the model call. In this example, the OpenAI service tier is set to 'priority' to enable faster responses.

### Method
Function call: generate()

### Parameters
#### providerOptions
- **openai.serviceTier** (string) - Optional - The service tier for the OpenAI model. Allowed values: "auto", "default", "flex", "priority". Example: "priority".
- **openai.reasoningEffort** (string) - Optional - The reasoning effort level. Allowed values: "none", "minimal", "low", "medium", "high", "xhigh". Example: "low".
- **openai.textVerbosity** (string) - Optional - The text verbosity level. Allowed values: "low", "medium", "high". Example: "low".

### Request Example
```tsx
const page = await generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  providerOptions: {
    openai: {
      serviceTier: "priority", // Enable faster responses
    },
  },
});
```

### Notes
Use designMode.providerOptions to override these options for design-mode requests.
```

--------------------------------

### ComponentData with props

Source: https://puckeditor.com/docs/api-reference/data-model/component-data

Example showing the props object, which requires a unique id to be defined.

```json
{
  "type": "HeadingBlock",
  "props": {
    "id": "HeadingBlock-1234", // Auto-generated
    "title": "Hello, world"
  }
}
```

--------------------------------

### ComponentData object structure

Source: https://puckeditor.com/docs/api-reference/data-model/component-data

A basic example of a ComponentData object representing a HeadingBlock instance.

```json
{
  "type": "HeadingBlock",
  "props": {
    "id": "HeadingBlock-1234",
    "title": "Hello, world"
  }
}
```

--------------------------------

### <Drawer.Item> with Custom Children

Source: https://puckeditor.com/docs/api-reference/components/drawer-item

Example of using <Drawer.Item> with a custom render function for children.

```APIDOC
## <Drawer.Item> with Custom Children

### Description
Renders a draggable item with custom content using the children render prop.

### Component
<Drawer.Item>

### Props
#### Required Props
- **name** (String) - Required - The name of the drawer item.

#### Optional Props
- **children** (Function) - Optional - A custom render function. The function receives render props including the original node.

### Render Props
- **children** (String) - The original node for the drawer item.

### Example
```tsx
import { Puck, Drawer } from "@measured/puck";

export function Editor() {
  return (
    <Puck>
      <Drawer>
        <Drawer.Item name="Orange">{() => <div>Orange 🍊</div>}</Drawer.Item>
      </Drawer>
    </Puck>
  );
}
```
```

--------------------------------

### Advanced grid example with PuckPreview

Source: https://puckeditor.com/docs/integrating-puck/multi-column-layouts

A complete implementation of a grid layout using inline components, showing the configuration and the data structure required to render multiple cards with varying column and row spans.

```tsx
<PuckPreview
  label="Advanced grid example"
  config={{
    root: {
      fields: {
        Content: {
          type: "slot",
        },
      },
      render: ({ Content }) => (
        <Content
          zone="default-zone"
          style={{
            display: "grid",
            gridTemplateColumns: "1fr 1fr 1fr 1fr",
            gridTemplateRows: "1fr 1fr 1fr",
            gap: 16,
          }}
        />
      ),
    },
    components: {
      Card: {
        inline: true,
        render: ({ content, spanCol, spanRow, puck }) => {
          return (
            <div
              style={{
                background: "white",
                border: "1px solid black",
                borderRadius: 4,
                padding: 16,
                gridColumn: `span ${spanCol}`,
                gridRow: `span ${spanRow}`,
              }}
              // Let Puck know this element is draggable
              ref={puck.dragRef}
            >
              {content}
            </div>
          );
        },
      },
    },

}}
data={{
    content: [],
    root: {
      props: {
        Content: [
          {
            type: "Card",
            props: { id: "Example-1", content: "1", spanCol: 2, spanRow: 2 },
          },
          {
            type: "Card",
            props: { id: "Example-2", content: "2", spanCol: 1, spanRow: 1 },
          },
          {
            type: "Card",
            props: { id: "Example-3", content: "3", spanCol: 1, spanRow: 1 },
          },
          {
            type: "Card",
            props: { id: "Example-4", content: "4", spanCol: 2, spanRow: 1 },
          },
          {
            type: "Card",
            props: { id: "Example-5", content: "5", spanCol: 1, spanRow: 1 },
          },
        ],
      },
    },
  }}
/>
```

--------------------------------

### Preview min items configuration

Source: https://puckeditor.com/docs/api-reference/fields/array

A ConfigPreview component demonstrating an array field with a minimum requirement of 1 item.

```tsx
<ConfigPreview
  label="Example"
  componentConfig={{
    fields: {
      items: {
        type: "array",
        min: 1,
        arrayFields: {
          title: { type: "text" },
        },
      },
    },
    defaultProps: { items: [{ title: "Apple" }, { title: "Banana" }] },
    render: ({ items }) => {
      return (
        <ul>
          {items.map((item, i) => (
            <li key={i}>{item.title}</li>
          ))}
        </ul>
      );
    },
  }}
/>
```

--------------------------------

### drawerItem override

Source: https://puckeditor.com/docs/api-reference/overrides/drawer-item

An example of how to override an item within the component drawer using the drawerItem override.

```APIDOC
## drawerItem

### Description
Override an item within the component drawer.

### Example
```tsx copy
const overrides = {
  drawerItem: ({ name }) => <div>{name}</div>,
};
```

### Props

#### children
- **Type**: ReactNode
- **Description**: The default node for the drawer item.

#### name
- **Type**: ReactNode
- **Description**: The name of the drawer item.

```

--------------------------------

### generate() with host parameter

Source: https://puckeditor.com/docs/api-reference/ai/cloud-client/generate

Shows how to set a custom Puck Cloud host using the 'host' parameter.

```ts
const page = await generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  host: "https://www.example.com/api",
});
```

--------------------------------

### Text field configuration example

Source: https://puckeditor.com/docs/api-reference/fields/text

A basic implementation of a text field within a component configuration.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        title: {
          type: "text",
        },
      },
      render: ({ title }) => {
        return <p>{title}</p>;
      },
    },
  },
};
```
Tokens:
Raw