Alt Text Field

Every image on the web needs an alt attribute. Images that convey meaning need descriptive text. Decorative images need an empty alt="", which tells screen readers to skip them entirely. Getting this wrong hurts accessibility.

Kirby SEO provides a dedicated alt-text field that handles both cases. It stores structured data instead of a plain string, so your templates always render the correct HTML attributes.

Adding the field

Add an alt-text field to any file blueprint:

# site/blueprints/files/image.yml
fields:
  alt:
    type: alt-text
    label: Alt Text

Editors see a text input with a toggle. The toggle marks an image as decorative: when active, the text input disappears because decorative images don't need a description.

AI generation

If AI Assist is configured, the field shows Generate and Customize buttons. The AI sees the actual image and writes alt text based on it, the filename, and the page context. Results stream in chunks and can be stopped early.

You can hide the Panel AI controls for a specific field by setting ai: false in the blueprint. This does not disable upload generation when autogenerate: true is set.

Auto-generation on upload

Set autogenerate: true to generate alt text automatically when an image is uploaded:

alt:
  type: alt-text
  autogenerate: true

When tobimori/kirby-queues is installed, generation runs through Kirby Queues. Without that plugin, it runs synchronously during the upload. See Background Processing for setup. On multilingual sites, a single AI call generates alt text for all languages at once.

Using alt text in templates

The plugin registers a toAltText() field method that returns an AltText object. Use its toAttr() method to get the correct HTML attributes, then spread them into your image helper:

<?= Html::img($file->url(), [
  'width' => $file->width(),
  'height' => $file->height(),
  ...$file->alt()->toAltText()->toAttr(),
]) ?>
// <img alt="A dog playing fetch" src="..." width="..." height="...">

// decorative image:
// <img alt="" src="..." width="..." height="...">

The field also works with plain string values from existing alt fields. If you migrate from a regular text field, toAltText() treats the old value as manual alt text.