Sylius Media Alt Text
Localised alt texts for product, category and avatar images in Sylius 2 - maintained in the admin or via the Admin API, output in Storefront and Shop API, decorative images, backfill command.
Sylius Media Alt Text
This documentation always describes the latest published version.
Overview
Sylius has no alt text field on images. This plugin adds one for product images, category images (taxons) and the profile pictures of admin users: editors maintain an alt text per image and language in the admin or through the Admin API, and the Storefront and Shop API output it. This covers the part of WCAG 2.1 "Non-text Content" and the BFSG (German Accessibility Strengthening Act) that concerns images.
Without maintained text nothing changes: the output stays what Sylius printed before (the product or category name). You can install the plugin right away and add the texts gradually.
The plugin alone does not make a shop BFSG-compliant. It closes the gap that Sylius has no alt text field on images at all; the rest of the shop still needs a proper accessibility audit.
graph LR
A["Editor in the admin"] --> D["Alt texts per image and language"]
B["Admin API"] --> D
C["Backfill command"] --> D
D --> E["Storefront (Twig)"]
D --> F["Shop API (alt)"]
Documentation
| Page | Content |
|---|---|
| Installation | Composer, bundle, routes, setup command, update, uninstallation |
| Configuration | Admin switch, maintaining alt texts, backfill command |
| Storefront | Where the text appears, template overrides, mmd_image_alt in your own theme |
| Shop API | alt field in Shop API responses, settings endpoint for headless clients |
| Admin API | Reading and writing alt, decorative and altTexts, error responses |
| Extending | Fallback providers, additional image types, services |
| Troubleshooting | Common problems, limitations, FAQ |
| Technical details | Architecture, structure, tables |
Features
| Feature | Description |
|---|---|
| Alt text per language | One text per image and enabled shop language, 255 characters maximum |
| Decorative images | "Decorative image" switch: the image outputs alt="" and is skipped by screen readers |
| Three image types | Product images, category images (taxons) and admin avatars |
| Admin editor | Directly in the image card, one collapsible section per language, the default language starts expanded |
| Admin API | Images return alt, decorative and altTexts; PUT and multipart upload accept altTexts and decorative |
| Shop API | Images return the resolved alt for the language of the request |
| Storefront | Product page, category header image, product cards and cart output the maintained text |
| Fallback | Requested language, then default language, then the product or category name |
| Backfill | mmd:media-alt-text:backfill pre-fills missing texts from product and category names |
| Global switch | One setting turns the output on or off for the whole shop |
Requirements
| Requirement | Version | Notes |
|---|---|---|
| PHP | 8.3 or newer | |
| Sylius | 2.2 or newer | Symfony 7.4 |
| Database | MySQL 8 / MariaDB | The migrations are MySQL DDL and refuse to run on other platforms |
License
Commercial license, see LICENSE in the repository.
Support
Email: support@markus-michalski.net