Images, audio, video, and other media can communicate information that is not available in text. They can also create barriers when people cannot see, hear, understand, or operate the content.

Plan accessible alternatives before producing or publishing media. Retrofitting captions, descriptions, transcripts, and accessible controls is slower and usually produces a worse result.

Configure Drupal image fields carefully

Drupal 11 image fields enable the alternative text field and make it required by default. Keep the alternative text field enabled for images that may convey information. Drupal also disables the image title field by default and describes enabling it as not recommended because it can cause problems for screen reader users.

A required alternative text field is useful for informative images, but it prevents an author from saving the intentional empty value required for a decorative image. Do not tell authors to enter a space, filename, or filler such as "decorative image." Instead, design the content model for the images it accepts:

Require meaningful alternative text when the field is only for informative images.
Keep decorative graphics in the theme when practical.
If authors can choose decorative images, provide a clear, tested way to record that decision and render alt="". This may require site-specific field design or validation.

The same image can serve different purposes in different contexts. Reusing a media item does not guarantee that its stored alternative text is correct everywhere it appears. Review the rendered result in context.

Preserve image attributes in Twig

Drupal 11 core's image.html.twig template renders the attributes prepared by Drupal:

<img{{ attributes }} />

Preserve attributes when overriding this template. Rebuilding the element from selected variables can remove its alternative text, dimensions, loading behavior, classes, or other attributes.

Drupal's Responsive Image template uses a picture element with one controlling img element. Keep the alternative text on that img. The source elements select image resources and do not need separate alternative text.

Write alternative text for the image's purpose

Alternative text replaces the purpose or information of an image in its current context. It is not a visual inventory and it is not primarily an SEO field. Ask what a person would miss if the image were unavailable.

Informative images

Describe the information needed to understand the surrounding content. Keep the text concise, but include enough to serve the same purpose as the image.

<img src="library-entrance.jpg"
  alt="Main library entrance with a ramp to the left of the stairs">

There is no WCAG rule that limits alternative text to 125 characters. Length depends on purpose and context. A complex image usually needs a short alternative and a separate structured description rather than an extremely long alt value.

Decorative or redundant images

Use an empty alternative attribute when an image adds no information or repeats information already available next to it:

<img src="divider.svg" alt="">

Use exactly alt="", with no space. Omitting the attribute can cause some screen readers to announce the filename. Do not use aria-label="decorative" or alternative text such as "image" or "spacer."

Functional images

When an image is the only content of a link or button, the alternative text should name the destination or action, not describe the picture.

<a href="/search">
  <img src="search.svg" alt="Search">
</a>

If visible text already names the control, use alt="" on an adjacent icon to avoid repetition.

Images of text

Use real text instead of an image of text when possible. Real text can reflow, resize, translate, and adapt to user preferences. When an image of text is necessary, such as a logo, provide the essential words in the alternative text unless the same words are already available next to it.

Complex images

Charts, diagrams, maps, and other complex images need the essential information in text. Provide:

a concise alternative that identifies the image and its purpose; and
a visible, structured description containing the important values, relationships, sequence, or conclusion.

Place the description near the image or provide a clearly associated link. Use headings, lists, and data tables when they communicate the information better than a paragraph. Do not rely on aria-describedby for a description whose headings or table structure must remain navigable.

A caption and alternative text have different purposes. A caption may identify the source or explain context. Alternative text replaces information supplied by the image. Do not automatically copy one into the other.

Handle CSS images and SVG

Use CSS background images only for presentation or when the same information is available as real text. Important information must not disappear when background images, custom styles, or high-contrast settings are unavailable.

For an SVG used as the source of an img, provide alternative text on the img. For inline SVG that conveys information or provides a control, give it an accessible name and expose only the semantics people need. Hide decorative inline SVG from assistive technology. SVG accessibility depends on its markup and context, so test the rendered result with browsers and screen readers rather than relying on one generic pattern.

Provide accessible audio and video

Choose the required alternatives from the information the media contains. Captions, transcripts, and audio description solve different barriers and are not interchangeable.

Captions

Provide accurate captions for prerecorded video with meaningful audio.
Provide accurate live captions for live video with meaningful audio when meeting WCAG 2.2 AA.
Include relevant speech, speaker identification, and non-speech sounds needed to understand the content.
Review and correct automatically generated captions before publication. Unreviewed automatic captions are not sufficient.

Transcripts

Provide a transcript for prerecorded audio-only content. Make it easy to find next to the media. Identify speakers and include meaningful non-speech audio.

A transcript of synchronized video is useful but does not replace captions for people who watch the video. A descriptive transcript also includes important visual information and supports people who cannot use either the audio or the visuals. WCAG places the media alternative for prerecorded synchronized media at Level AAA. Treat it as aspirational in a project targeting AA, while recognizing the users who need it.

Description of visual information

Provide audio description for important visual information in prerecorded video when that information is not already available in the main audio. This includes actions, scene changes, charts, demonstrations, and text displayed on screen.

For new instructional or presentation video, plan integrated description. Speakers can state names, read essential on-screen text, and describe what they demonstrate as part of the main narration. This often avoids a separate audio-description track while producing a clearer video.

Use an accessible media player

Drupal can store and display media, but accessibility also depends on the player, embed provider, configuration, and content. A third-party player does not transfer responsibility to the provider.

Test that the player:

works with a keyboard and does not trap focus;
provides visible focus indicators;
gives every control an understandable name, role, state, and value;
supports play, pause, stop, volume, seeking, captions, and audio description where those features apply;
keeps controls available at zoomed and narrow viewport sizes;
does not require hover, dragging, or a precise pointer movement as the only method of operation; and
does not obscure captions or other content with controls.

Avoid autoplay. If audio starts automatically and continues for more than three seconds, provide a way to pause or stop it, or control its volume independently from the system volume. Provide a way to pause, stop, or hide automatically moving content when WCAG requires it.

Do not publish content that flashes in a way that can trigger seizures. Avoid rapid flashing rather than trying to calculate the threshold after production.

Test the rendered content

Inspect every rendered img for an appropriate alt attribute.
Compare alternative text with the image's purpose in context.
Confirm that decorative images are ignored by a screen reader.
Check complex images against their visible descriptions.
Review captions for accuracy, timing, speaker identification, and important sounds.
Check transcripts and descriptions against the complete media.
Operate the media player with a keyboard and a screen reader.
Test the player at supported breakpoints and at 200% and 400% zoom.
Run an automated accessibility checker, then complete the manual checks. Automated tools cannot judge whether an alternative conveys the correct meaning.