API ReferenceAIAI PlugincreateAiPlugin

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

Param	Example	Type	Status
`chat.attachments`	`{ enabled: true }`	Object	-
`chat.examplePrompts`	`{}`	Object	-
`chat.onSubmit`	`(prompt) => console.log(prompt)`	Function	-
`host`	`"https://www.example.com/api/puck"`	String	-
`prepareRequest`	`(options) => options`	Function	-
`scrollTracking`	`false`	Boolean	-

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

`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

Prop	Example	Type
`options`	`{ headers: {}, credentials: {}, body: {} }`	Object

`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.

Returns

Prop	Example	Type
`options`	`{ headers: {}, credentials: {}, body: {} }`	Object

`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",
  };
};

Installation