58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
|
---
|
||
|
|
title: Alt Text Field
|
||
|
|
intro: Structured alt text for images, with AI generation and a decorative toggle
|
||
|
|
---
|
||
|
|
|
||
|
|
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 a `alt-text` field to any file blueprint:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# 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](1_features/04_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 word by word and can be stopped early.
|
||
|
|
|
||
|
|
You can disable AI for a specific field by setting `ai: false` in the blueprint.
|
||
|
|
|
||
|
|
### Auto-generation on upload
|
||
|
|
|
||
|
|
Set `autogenerate: true` to generate alt text automatically when an image is uploaded:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
alt:
|
||
|
|
type: alt-text
|
||
|
|
autogenerate: true
|
||
|
|
```
|
||
|
|
|
||
|
|
By default, this runs synchronously during the upload. For better performance, you can offload it to a background queue. See [Background Processing](2_customization/10_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:
|
||
|
|
|
||
|
|
```php
|
||
|
|
<?= 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.
|