Anyone know how to associate a caption to a image that gets uploaded into a media library field? I can get the name of the file to show up but I can't see how to associate a caption to the image. I have the image library filed set to allow unlimited items to be uploaded to it so I can have an array of images returned when I display it in my layout builder block. I got the css to style the image array in a grid format but now I need to somehow include a related field to the image which contains the caption text. I tried creating a view but I could only get all of the images in the image library from all the nodes that had uploaded images and not just the images uploaded to a specific node that was being viewed like a contextual or relationship in the advanced section of the view form. Because the image once uploaded to the media library dose not seem to have any relationship to the node it is uploaded into that I can filter or sort on for the context connection. Has some one written or know about a contributed module that does add the caption field association to a image or for that matter any other type of media uploaded to the media library?

  • 1
    Just write the caption into the name field. The filename is just a default value for the name field, there is no technical necessity to keep the filename in the name field.
    – Hudri
    Aug 26, 2021 at 15:44

1 Answer 1


Short answer: yes, you can get Drupal to associate captions to Media Library images.

Longer answer: there are at least two different angles to approach this from.

Approach #1: Media entities are fieldable just like any other entities, so you can add a Caption field to the Media entity itself.

Go to /admin/structure/media/manage/image/fields and click "Add field" to add a caption for Media image entities.

Don't forget to adjust the Form display (/admin/structure/media/manage/image/form-display) and the Display (/admin/structure/media/manage/image/display) to your liking.

If necessary, you can set up different view modes with custom display settings, and you can override a Twig template to control the layout of the Media image entity.

Caveats to Approach #1: This approach means that the caption is bundled with the media image, so if you use the Media image entity on multiple pages, editing the caption will change the caption everywhere -- which is convenient if that is exactly what you want, but inconvenient if it causes unexpected side effects. It also means that the caption field may not be easily edited while editing the node that the Media image is used on.

Approach #2: One common workaround for these shortcomings is bundling the Media image entity reference field with a Caption field in a multi-field bundle using something like Paragraphs (other options include Field Collection or Entity Constructor Kit). This will allow users to edit the caption while editing the node that the Paragraph appears on. It also allows you to have a different caption each time the media image is used.

Caveats to Approach #2: This approach requires contributed modules; doing it in Drupal core is theoretically possible by creating a custom Content Type with the media entity reference field and the caption field, but the UX would not be quite as nice.

Approach #3: Finally, I should note that the two options can be combined. With savvy Twig conditionals, you can have your Paragraph template use the value provided in a "Caption Override" field in the Paragraph if it is available, or fall back on a global default caption provided by a field in the Media entity itself.

  • 1
    This was super helpful. After I implemented this I tried adding a media field to the image so I could also attach another media item to it. I had a external video media type field that I wanted to attach a pdf transcript to so that was super helpful. Aug 26, 2021 at 18:03
  • You might want to keep these extra fields to a minimum, unless you are certain that you will never have a use for a Media Image entity that does not have an attached video. Imagine that you're a painter and the different entity types are colors. You just poured some red paint into your green paint bucket for "convenience" and now you can never paint a green tree without getting plaid leaves. Do yourself a favor and check out Paragraphs before you mess up all your media types this way! Aug 26, 2021 at 19:08
  • 1
    That is a very valid point to take into consideration. That is what I considered when I added the extra field for the pdf. So I left it as optional to upload a pdf to the field. With alternative media requirements to satisfy the 504 and broader 508 compliance for video I needed a easy way to provide a descriptive transcript for video assets. I agree this solution would not be for every person but it works for my needs. Aug 27, 2021 at 7:06
  • 1
    As a a benefit once posted in a node if I ever wanted to add a pdf later it is easy to edit the field and add it. The win for me at that point is that every where that media file was posted will get the updated file instantly with one operation. Beats updating multiple nodes that have a image field with the image uploaded to it. Aug 27, 2021 at 7:07
  • That's good. It looks like in your case, you really will benefit from having your fields tightly coupled with the Media entity, so you can update the PDF once and have the change applied everywhere. The nice thing about Drupal is that it's flexible enough to be used in a lot of different ways! Aug 27, 2021 at 17:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.