media_reference_override

When editors reuse the same image across multiple pages or content types in Drupal, the alt text, title, and caption stored on the media entity are global — changing them affects every single place that media item appears. The only built-in workaround is duplicating the media item just to change its description, which pollutes the Media Library and makes long-term maintenance a nightmare.

This module solves that by allowing editors to override specific fields of a referenced media item — such as the alt text or title of an image — directly at the point of reference, without touching the original media entity. The override is stored on the referencing entity (the node, paragraph, or block), not on the media itself, so the same image can carry a completely different alt text on a landing page than it does on a press kit — while the shared media entity remains untouched and reusable everywhere else.

New to Drupal? Think of it this way: your Media Library is a shared pool of assets. Normally, changing an image's description changes it everywhere that image appears. This module gives each piece of content its own "local note" about how to describe that media item — without affecting anyone else using it.

No coding required: just install, go to Manage form display, enable overrides on your media reference field, and the inline override fields appear for editors automatically — no new field types, no template changes, no developer involvement for each new use case.

Features

The core functionality of this module is straightforward: it extends Drupal's standard media reference field to allow per-reference field overrides. When an editor selects a media item on a node or paragraph, an inline override section appears beneath it — allowing them to enter context-specific values such as a custom alt text or title. Those values are stored on the referencing entity, not the media entity, so the original media remains untouched and reusable.

Key features include:

Override one or more fields on a referenced media entity at the point of reference (e.g., alt, title) without modifying the shared media entity.
Override values are stored on the referencing entity (node, paragraph, block content, etc.), keeping the original media entity clean, canonical, and reusable across the entire site.
Works with Drupal's core Media and Media Library systems — no new field types or widget replacements required.
Provides an extended field widget that shows an inline override form directly inside the content editing experience, below the selected media item.
Provides a field formatter that automatically substitutes override values when rendering media, ensuring the correct contextual output appears in the final HTML.
The module integrates using hook_field_widget_single_element_form_alter() and hook_field_formatter_info_alter() — no separate field type is required, and it works with your existing media reference fields without migration or reconfiguration.
The frontend rendering impact is zero when no override is set — the module only alters output when an explicit override value has been entered by an editor.

When and why would someone use this module? Use cases include:

Accessibility compliance: The same hero image appears on multiple pages, each requiring a different, context-specific, meaningful alt text to meet WCAG standards.
Press & marketing: One office photo is reused across an About page and a Press Kit, each needing a different caption without duplicating the asset.
SEO optimization: Different pages referencing the same image benefit from page-specific alt attributes that reflect their unique content context.
Editorial independence: Content teams manage contextual metadata without touching the shared Media Library or filing a developer request.
Works in: content types, Paragraphs, Layout Builder blocks, Views, and any fieldable entity with a media reference field.

Post-Installation

After enabling the module, no new configuration pages or content types are created — it integrates directly into the existing field configuration interfaces:

Go to Administration → Structure → Content types → [Your Type] → Manage fields and add or edit a media reference field.
Under Manage form display, open the widget settings (gear icon) for your media reference field. You will find new options to enable overrides for specific media fields — for example, enabling alt text override for Image media types.
Configure which fields can be overridden. The module presents a list based on the media types allowed by that reference field.
Save your configuration and clear caches.
When editors create or edit content, the media widget now shows an inline override section beneath the selected media item, where they can enter context-specific values without leaving the content form.
On the Manage display tab, no separate formatter configuration is required — the module hooks into the rendering pipeline automatically and substitutes override values wherever they exist.

Clear caches (drush cr or via the UI at Administration → Configuration → Performance) if override fields don't appear immediately after enabling the module.

Additional Requirements

This module requires no external libraries or third-party APIs. The only requirements are:

Drupal core ^10 || ^11
Core Media module (must be enabled) — provides the media entity system this module extends.
Core Media Library module (recommended, enabled by default with the Standard profile) — required for the Media Library widget integration.

Similar projects

Several modules tackle the problem of contextual media overrides, but none offer the same balance of simplicity, zero patch requirements, and native Drupal integration that Media Reference Override provides:

Entity Reference Override — Covers any entity reference, not just media. That broader scope adds complexity and configuration overhead that most sites don't need. Media Reference Override is purpose-built for media, offering a leaner codebase and a simpler editorial UI for the most common use case.
Media Library Media Modify — A powerful and feature-rich module, but it requires patches to Drupal core to function, which adds maintenance overhead on updates. Media Reference Override works out of the box with unpatched Drupal core.
Media Image Style Formatter — Focused on display style variation rather than metadata overrides like alt text or title. Both modules complement each other well if you need both display and metadata control per reference.
Core approach (multiple media view modes) — Drupal core allows creating separate view modes on media entities to control display. This works well for display variation but does not address per-reference metadata. Media Reference Override fills that gap by storing overrides at the reference level.
Custom theme preprocess hooks — A valid developer approach for custom projects, but it requires code maintenance per theme and is not accessible to content editors. Media Reference Override brings the same capability into the UI without any code.

Bottom line: Media Reference Override is the only solution that is patch-free, no-code, purpose-built for media references, and fully manageable by editors — making it the most practical choice for production Drupal sites of any size.

Recommended projects

I also maintain and recommend the following modules. None of them rewrite or override Drupal's core output — they integrate cleanly with the existing system, extend its native capabilities, and work perfectly alongside this module:

Advanced Image Media Attributes Formatter — Extends Drupal's native image field formatters to expose additional HTML attributes (alt, title, class, etc.) as configurable options in the formatter settings. Pairs naturally with Media Reference Override for fine-grained, no-code output control.
CKEditor Media Image Style — Adds a style selector to the CKEditor 5 media toolbar so editors can choose an image style per embed without creating new view modes. Brings the same contextual display flexibility inside rich text fields that Media Reference Override brings to reference fields.
CKEditor Media Title — Lets editors set a custom title attribute on media images embedded through CKEditor 5, directly from the media toolbar. Extends Drupal's native media embed without replacing the rendering pipeline.
Logo Image Enhanced — Extends Drupal's built-in site logo handling with additional image field controls, giving sites more flexibility over how the logo is rendered and attributed without overriding theme templates.
Media Image Style Formatter — Extends the core "Rendered entity" formatter for media reference fields to allow per-context image style overrides without creating extra view modes. A lightweight companion for teams focused on display variation alongside metadata overrides.
Htaccess — Provides a UI for managing .htaccess rules directly from the Drupal admin interface. Useful for hardening production environments without manual file editing.

Commercial Support

This module is developed and maintained by Nelo.
The maintainer is available for professional consulting and architectural guidance related to media systems, production Drupal implementations, and enterprise content architecture.

drupal.org/u/nelo_drup

Supporting this Module

- Check out our sponsor, Dom Host Seo, who made this module possible with their support!

Community Documentation

Currently no external videos or demo sites are available. The module includes detailed help text accessible via Help > media_reference_override.

For questions, bug reports, or feature requests, please use the issue queue on Drupal.org.