How to add captions to media library items?

Question

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?

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.