Adding alt text - ButterCMS Docs

Overview

Guides and tutorials

Creating and editing content

Managing media

Publishing lifecycle

Versioning and history

Authentication

Collaborating with teams

Localization

Multi-site and environments

SEO

AI assistant

The addition of alt text is essential for accessibility and SEO. Alt text is used by screen readers to give visually-impaired users context about the image being displayed. Search engines also use alt text to understand and index your images.

How to add alt text

Access your Media Library
Select an image or upload a new one
Add alt text via the “Alternative Text” field (located below the Name field)

Media Library Alt Text

Click the Save button to save your changes

Accessing alt text via API

To view the alternative text in your API response, include the following parameter to your API request URL or the ButterCMS API client — alt_media_text=1. Your API response for media will look like this:

{
  "image": {
    "alt": "ACME Logo",
    "url": "https://cdn.buttercms.com/ce8qgAuNTNaXuHvZj4xt"
  }
}

Setting alt text via the Write API

When creating or updating pages and collection items through the Write API, a Media field accepts either a URL string or an object with url and alt. Alt text is optional and can be up to 255 characters.

{
  "fields": {
    "image": {
      "url": "https://example.com/acme-logo.png",
      "alt": "ACME Logo"
    }
  }
}

The image is downloaded to your Media Library as usual, and the alt text is stored on the field. It is returned by the Read API when you include alt_media_text=1, so you can fetch a page, edit the response, and send it back without losing alt text. Sending a plain URL string for a Media field replaces any alt text previously set on that field.