A blueprint configures Copilot in two places: the view button's props under buttons, and the copilot key of a writer or textarea field.

View Button Configuration

The Copilot view button can be added to any Panel view (site, page, file, user) alongside the default buttons like the preview button or settings dropdown. Configure its behavior with props in your blueprints:

buttons:
  copilot:
    label: AI Assistant
    userPrompt: Generate homepage content including a headline, intro paragraph, and three key features with descriptions.
    theme: info-icon
  open: true
  preview: true
  languages: true

buttons:
  copilot:
    label: AI Assistant
    userPrompt: |
      Write a complete landing page for "{title}": a compelling headline, introduction, three benefit sections, and a call-to-action.
    theme: info-icon
  open: true
  preview: true
  settings: true
  languages: true
  status: true

buttons:
  copilot:
    label: AI Assistant
    userPrompt: Generate image metadata including a descriptive title, alt text, caption, and relevant tags based on the visual content.
    theme: info-icon
  open: true
  settings: true
  languages: true

The view button opens a prompt dialog that allows you to generate content for a single field or multiple fields at once. See View Button for how it looks in the toolbar.

Add the Button to Every View

To add the button to every site, page, or file view without editing each blueprint, set Kirby's panel.viewButtons option. It replaces the defaults the same way buttons in a blueprint does, and a blueprint that sets buttons wins over it:

return [
    'panel' => [
        'viewButtons' => [
            'site' => ['copilot', 'open', 'preview', 'languages'],
            'page' => ['copilot', 'open', 'preview', '-', 'settings', 'languages', 'status'],
            'file' => ['copilot', 'open', 'settings', 'languages']
        ]
    ]
];

Written as a map like a blueprint's buttons, the option also takes props such as userPrompt. A Kirby query in userPrompt or systemPrompt resolves only in the blueprint.

View Button Properties

label String

Custom label for the view button. The default depends on the Panel language (e.g., "Copilot" for English).

buttons:
  copilot:
    label: AI Assistant

userPrompt String

Default user prompt that appears when the generation dialog opens. Without a predefined prompt, the input field will be empty. Users can edit the prompt before generating content.

buttons:
  copilot:
    userPrompt: 'Write a landing page for "{title}": headline, intro, three benefits, and call-to-action.'

A Kirby query in the view button or the section resolves against the current model, so editors can write the prompt themselves in a field:

buttons:
  copilot:
    userPrompt: "{{ page.customPrompt.value }}"

Note the two syntaxes side by side: {{ ... }} is a Kirby query resolved in the blueprint, while {field} is a placeholder resolved when the prompt is sent.

systemPrompt String

Custom system prompt that controls how the AI model structures and formats the generated content. Users cannot see or edit this prompt.

Defaults to the global system prompt if not set locally.

buttons:
  copilot:
    systemPrompt: You are a technical writer specializing in documentation. Use clear, concise language.

Kirby queries resolve here too, on the same terms as userPrompt.

icon String

Custom icon for the view button.

Default: sparkling
Options: Any of the default Kirby Panel icons or a custom icon like copilot-ai-generate.

buttons:
  copilot:
    icon: copilot-ai-generate
    theme: info-icon

theme String

Controls the visual appearance and color theme of the button.

Default: notice-icon
Options: passive, white, info, positive, warning, notice, negative, love, aqua, purple, dark, *-icon variants (e.g., positive-icon, negative-icon)

buttons:
  copilot:
    theme: info-icon

logLevel String

Set the logging level for debugging AI generation. Inspect the browser console to see logs.

Options: error, warn, info, debug

buttons:
  copilot:
    logLevel: info

Field Properties

A writer or textarea field takes its Copilot props under its own copilot key.

copilot.userPrompt String

Default user prompt that appears when the field's Copilot button or shortcut opens the dialog. Users can edit it before generating content. Placeholders resolve, Kirby queries don't.

fields:
  text:
    type: writer
    marks:
      - bold
      - italic
      - "|"
      - copilot
      - copilot-suggestions
    copilot:
      userPrompt: Write a product description for "{title}". Highlight benefits, not features. Max 200 words.

fields:
  description:
    type: textarea
    buttons:
      - bold
      - italic
      - "|"
      - copilot
    copilot:
      userPrompt: Summarize "{title}" in 2-3 sentences. Focus on the main value proposition.

marks and buttons replace Kirby's defaults, so the snippets list every entry the field keeps. See Toolbar Buttons for how the prompt fills the dialog.

Configuration Precedence

The view button applies its properties in this order, each overriding the one before:

1. Default values (built into the plugin)
2. Global configuration (in config.php)
3. View button props (in blueprints)

The Copilot section takes the view button properties in the same order, plus its own. A field's copilot.userPrompt applies only to the dialog that field opens.