API ReferenceAIConfigurationFields

Field AI Config

Configure AI behavior for a field. Available for all Puck fields.

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

Params

Param	Example	Type	Status
`instructions`	`"Always use caps"`	String	-
`exclude`	`false`	Boolean	-
`required`	`true`	Boolean	-
`schema`	`{}`	JSONSchema	-
`stream`	`true`	Boolean	-

Optional params

`instructions`

Instructions that must be taken into account when considering this field.

const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
          ai: {
            instructions: "Always use caps",
          },
        },
      },
      // ...
    },
  },
};

`exclude`

Exclude this field when generating a page. false by default.

const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
          ai: {
            exclude: true,
          },
        },
      },
      // ...
    },
  },
};

`required`

Explicitly mark this field as required (true) or optional (false). By default, any field with a default value in defaultProps is considered required.

const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
          ai: {
            required: true,
          },
        },
      },
      // ...
    },
  },
};

`schema`

A custom JSON Schema for this field. By default, Puck AI will generate a schema based on the field type.

Useful when using custom, external, or user fields that Puck can’t infer.

const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "custom",
          render: () => <input />,
          ai: {
            schema: { type: "text" },
          },
        },
      },
      // ...
    },
  },
};

`stream`

Control when a field value is streamed to the client when using the AI plugin. Use this for fields, like image URLs, that can’t be rendered until complete.

Accepts a boolean value, with the following behavior:

true: Stream the value to the client as soon as available
false: Wait for the value to finish generating before streaming the value to the client

const config = {
  components: {
    ImageBlock: {
      fields: {
        src: {
          type: "text",
          ai: {
            stream: false, // Don't stream image URLs
          },
        },
      },
      // ...
    },
  },
};

By default, the following field types are streamable by default:

array
custom
number
text
textarea

Components