createAiPlugin

Create a plugin that shows a chat interface for interacting with Puck AI.

import { createAiPlugin } from "@puckeditor/plugin-ai";
import "@puckeditor/plugin-ai/styles.css";
 
const aiPlugin = createAiPlugin();
 
export function Editor() {
  return (
    <Puck
      plugins={[aiPlugin]}
      // ...
    />
  );
}

Params

Optional params

chat.attachments

Configure file attachments for the chat interface.

const aiPlugin = createAiPlugin({
  chat: {
    attachments: {
      enabled: true,
    },
  },
});

chat.attachments.enabled

Enable or disable file attachments. Defaults to true.

chat.attachments.accept

An array of accepted file types. Supports MIME type wildcards (e.g. image/*), file extensions (e.g. .pdf), or exact MIME types.

Defaults to ["image/*", ".pdf", ".doc", ".docx", ".txt", ".md"].

const aiPlugin = createAiPlugin({
  chat: {
    attachments: {
      enabled: true,
      accept: ["image/*", ".pdf"],
    },
  },
});

chat.attachments.maxFiles

The maximum number of files that can be attached to a single message. Defaults to 5.

chat.attachments.maxSizeBytes

The maximum file size in bytes. Defaults to 10485760 (10 MB).

chat.examplePrompts

Example prompts to show beneath the text input. Will send the prompt on click.

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

chat.placeholder

Custom content to show in the message area when the chat has no messages. Defaults to the built-in Puck AI placeholder.

const aiPlugin = createAiPlugin({
  chat: {
    placeholder: (
      <div>
        <h2>Start creating</h2>
        <p>Describe the page you want to build.</p>
      </div>
    ),
  },
});

chat.onSubmit(prompt, options)

A callback that receives the prompt and any attachments when the user submits the form.

const aiPlugin = createAiPlugin({
  chat: {
    onSubmit: (prompt, options) => {
      console.log(prompt, options?.attachments);
    },
  },
});

chat.onFinish(options)

A callback that runs after a response finishes and all queued page changes have been applied.

const aiPlugin = createAiPlugin({
  chat: {
    onFinish: ({ message, isAbort, isDisconnect, isError, finishReason }) => {
      if (!isAbort && !isDisconnect && !isError) {
        console.log("Page generation finished", message, finishReason);
      }
    },
  },
});

The options object also includes the complete messages array.

designMode

Show the design mode toggle in the chat composer, letting users switch between assembly and design mode. Hidden by default, and requires enabling design mode on the server.

const aiPlugin = createAiPlugin({
  designMode: {
    visible: true,
  },
});

defaultMode

Set the mode used when the chat first loads. Defaults to "assembly".

const aiPlugin = createAiPlugin({
  defaultMode: "design",
});

scrollTracking

Automatically scroll to the element being modified, unless the user scrolls manually. It is enabled by default.

const aiPlugin = createAiPlugin({
  scrollTracking: false,
});

host

Configure the API host that the plugin will call during a chat. This should be your server.

const aiPlugin = createAiPlugin({
  host: "https://example.com/api/puck/chat",
});

prepareRequest(opts)

A callback to customize the request before API calls made by the plugin. Use this to add custom headers, add metadata to the body, or change credentials.

const aiPlugin = createAiPlugin({
  prepareRequest: async (options) => {
    return {
      headers: {
        Authorization: "Bearer my-token",
      },
    };
  },
});

Args

options.headers

The default headers that will be used in the request.

options.credentials

The default credentials that will be used in the request.

options.body

The default body that will be sent to the API. Includes:

• chatId: The id of the current chat.
• trigger: The trigger that initiated the message.
• messages: The current list of messages in the chat.
• pageData: The current Puck data.
• config: The current Puck config.
• mode: The current mode ("assembly" or "design").

Returns

options.body

A partial body object containing additional metadata to send to the API. Will be spread into the default body.

const prepareRequest = async (options) => {
  return {
    body: {
      userId: "1234",
    },
  };
};

options.headers

A partial headers object containing additional headers to send to the API. Will be spread into the default headers.

const prepareRequest = async (options) => {
  return {
    headers: {
      Authorization: "Bearer my-token",
    },
  };
};

options.credentials

The credentials to use in the request. Overrides the default credentials.

const prepareRequest = async (options) => {
  return {
    credentials: "include",
  };
};