AI Alt Text Generator for CraftCMS

The AI Alt Text Generator for CraftCMS is a plugin that automatically creates high-quality, descriptive alt text for images in your CraftCMS media library. Powered by the AltTextLab API, it uses advanced AI to generate accessible and SEO-friendly image descriptions, saving you time and improving your website’s accessibility compliance.

GitHub Repository

Features

Automatic generation on upload – Instantly generate alt text for newly uploaded images without any manual work.
Bulk generation for your entire assets library – Generate Craft CMS image alt text for all existing images in one pass.
Craft Commerce support – When an image is linked to a Commerce product or variant, the plugin reads product name, brand, color, and material to generate product-specific alt text.
Multi-site and multi-language – Generate alt text in each Craft site's configured language automatically. One API call per unique language, with results shared across sites using the same locale.
4 AI writing styles – Choose between descriptive, neutral, matter-of-fact, and minimal output styles for consistent tone across your entire site.
Free plan, no OpenAI key required – Every AltTextLab account includes 25 free credits per month, permanently. No OpenAI account, no credit card required to start.

Requirements

This plugin requires:

Craft CMS 5.0.0 or later
PHP 8.2 or later
AltTextLab API key (You can create one here)

Installation

You can install this plugin from the Plugin Store or with Composer.

Alt text generator setup

Make sure the plugin is installed in your CraftCMS site.
If you don't have an AltTextLab account yet, create one here.
Go to the API Keys page, click Create API Key, and copy the generated key.
In CraftCMS, open AltTextLab → Settings and paste the API key into the AltTextLab API Key field. Save the changes.
AltTextLab is now connected. Enable automatic generation, or go to AltTextLab → Bulk Generation to start processing your existing Craft CMS image assets.

How to use AltTextLab alt text generator

Automatic alt text generation
Enable the Auto-generate alt text for new assets toggle in the plugin settings. Once enabled, the plugin will automatically generate alt text for all newly uploaded images.
Bulk generation for the entire media library
To generate alt text for all images in your CraftCMS media library, go to AltTextLab → Bulk Generation and click Run generation. This will create a new Job, which you can track in Queue Manager or under AltTextLab → Bulk Generation History.
Bulk generation for selected media
If you only want to generate alt text for specific images, select them in the Assets tab, open the action menu, and choose Bulk generation.

Settings

All settings are available under AltTextLab → Settings.

Auto-generate alt text for new assets

When enabled, the plugin automatically generates alt text for every newly uploaded image. Generation takes a few seconds, so the alt text may not appear immediately — simply check again after a short delay.

Automatically use each site's language (multi-site)

Enable this to generate alt text in the language configured for each Craft site (Settings → Sites) instead of using a single language.

When this mode is active:

The plugin reads the language from each site's locale (e.g. en-US, de, fr).
Sites that share the same language are grouped together — only one API call is made per unique language, keeping usage efficient.
Alt text is saved separately for every site, so each localized version of an asset gets its own description.

Important: The alt text field (native alt or your custom field) must have its Translation Method set to Translate for each site or Translate for each language. You can configure this in Settings → Assets (for the native alt field) or Settings → Fields (for custom fields). The plugin will show a warning if the field is not translatable.

Language

Choose a language for generated alt text from the Language dropdown (130+ languages available). When the multi-site switch above is off, every asset receives alt text in this language regardless of which site it belongs to. When the multi-site switch is on, this dropdown is ignored.

Model type

Select the style of generated descriptions:

Use account default — uses the style configured in your AltTextLab account.
Descriptive — rich, detailed descriptions.
Neutral — balanced tone without subjective language.
Matter-of-fact — concise, objective descriptions.
Minimal — shortest possible descriptions.

Field for alt text

Choose which field the plugin writes alt text to. By default, the native Alt field is used. You can also select any Plain Text custom field attached to your Asset volume's field layout.

If you change this setting after assets have been processed, run Bulk Generation to re-generate alt text into the new field.

This site is reachable over the public internet

Once your site is publicly accessible and each image can be reached over the internet, we highly recommend enabling this setting. It makes the generation process faster and ensures that images are not transferred through AltTextLab's servers.

If you are developing locally or your site is not publicly accessible, keep this setting disabled.

Disable volumes (exclude specific images)

Select one or more Asset Volumes to exclude from alt text generation. Assets stored in disabled volumes will be skipped during both automatic and bulk generation.

Exclude images by regex

For precise exclusion control, match files by their full file system path using a regular expression. Define the following in your .env file:

# Examples (pick one and adjust to your needs)
ALT_TEXT_LAB_EXCLUDE_REGEX=~/(thumbnails|icons)/~i
# Or exclude anything in /uploads/tmp/
# ALT_TEXT_LAB_EXCLUDE_REGEX=~/uploads/tmp/~
# Or exclude all SVGs inside "branding" folder
# ALT_TEXT_LAB_EXCLUDE_REGEX=~branding/.+\.svg$~i

Notes:

The pattern is applied against the asset's full local path, which includes the volume file system path, optional subpath, and the asset path.
You may provide a PCRE pattern with delimiters (e.g., ~/pattern/~i). If you omit delimiters, the plugin will attempt to wrap your pattern automatically.
Regex-based exclusions apply to both automatic generation and bulk operations.

Craft Commerce integration

If you have Craft Commerce installed, the plugin can automatically enrich alt text generation with product context. When an image is linked to a Commerce product or variant, the plugin reads product data (name, brand, color, material) and sends it to the AltTextLab API alongside the image. This allows the AI to generate more accurate, product-specific descriptions — for example, "Blue cotton t-shirt with a round neck" instead of a generic "A t-shirt on a white background".

The Commerce section appears in plugin settings only when the Commerce plugin is installed and enabled.

How it works

At generation time, the plugin checks whether the asset is related to any Commerce variant or product.
If a linked variant is found, its parent product is resolved automatically.
The configured product fields (name, brand, color, material) are read and passed to the API as additional context.
If no linked product or variant is found, generation proceeds as usual without any extra context.

Commerce settings

All Commerce settings are available under AltTextLab → Settings → Commerce.

Product name for alt text

Controls which title is sent to the API as the product name:

Use product name (default) — uses the title of the linked product.
Use variant title — uses the title of the linked variant (useful when variant titles carry colour/size information, e.g. "Blue / XL"). Falls back to the product title if no variant is linked.

Brand field handle

The handle of a Plain Text (or similar) field on the product that stores the brand name (e.g. brand). Leave empty to skip brand context entirely.

Example: if your products have a field with handle brand containing "Acme Co.", enter brand here and the AI will receive that value as additional context.

Color source

Determines which element the color field is read from:

Use product color field (default) — reads the color field from the product.
Use variant color field — reads the color field from the variant (useful for products where color is a variant-level attribute).

Color field handle

The handle of the field that stores the color value (e.g. color). Can point to the product or variant depending on Color source. Leave empty to skip color context.

Material source

Determines which element the material field is read from:

Use product material field (default) — reads the material field from the product.
Use variant material field — reads the material field from the variant.

Material field handle

The handle of the field that stores the material value (e.g. material). Can point to the product or variant depending on Material source. Leave empty to skip material context.

Tip: You can mix sources. For example, set Product name to Use variant title, Color source to Use variant color field, and Material source to Use product material field — the plugin will read each attribute from the appropriate element independently.

Supported file types

The Alt Text Generator for CraftCMS supports the following image formats:

JPEG / JPG
PNG
WebP
AVIF
SVG

Troubleshooting

The plugin includes a AltTextLab → Logs page where you can view any errors related to alt text generation.
Alt text generation for bulk operations is processed through Craft's queue system, so if generation seems to be taking a long time, check the Queue Manager.
All errors should also be logged, review your queue.log files for more details.

Support and feedback

If you enjoy the plugin, please leave a review on the Plugin Store — it helps other Craft developers discover it.

Found a bug or have an idea for improvement? Open an issue on GitHub.

For general questions or help getting started:

Website: https://www.alttextlab.com
Support Email: contact@alttextlab.com
Contact us