Media library upload form should use source field label and description

currently i am working on that ......

Interesting idea @DuaelFr. Tagging for a UX review.

Referencing #3149764: Media Library: Help text from file field missing, which I am closing as a duplicate of this one.

Fixing test.

Fixing Test.

Tested the above patch on 9.2.x dev version, it works fine
Before patch
After patch .RTBC

Re-rolled from #12

LGTM.

Nitpick: I would have probably added just one method, getSouceFieldDefinition(). But I think it's fine as it is.

I don't know if I agree with the idea of adding two new, very specific methods for two very specific keys of the input element. IMHO, subclasses should just override buildInputElement() and update the #title and #description properties directly.

Also, it looks like this needs a reroll. Therefore, could we switch it to a merge request?

To be very honest...I'm wondering if this belongs in core.

I think that, with maybe a couple of minor internal tweaks, this is something that would be quite feasible in contrib. It's also something that could be configured differently for different media types. With some media types, it might be clearer to say "Add files" or "Add images" than just "Images". Being able to set a custom field label and description in the media type configuration might be more useful to site builders, and could be implemented by something like Media Library Extras.

Thoughts?

Re-roll patch created for 9.3.x.

> I don't know if I agree with the idea of adding two new, very specific methods for two very specific keys of the input element. IMHO, subclasses should just override buildInputElement() and update the #title and #description properties directly.

Ok, well two of us agree that we shouldn't add two new methods.

But I don't think plugin subclasses should have to do this, they will just be repeating the same work each time:

- the plugin has a source field
- the source field has a label and description in its configuration
- the media library upload form should get the label and description from the source field

> To be very honest...I'm wondering if this belongs in core.

I definitely don't think this should go in contrib.

The media library is showing a form to add media of a particular type, and showing the source field for that type. It's simply good UX to show the widget for that field properly -- with its configured label and description.

It's simply good UX to show the widget for that field properly -- with its configured label and description.

While I agree in principle, I'm wondering how it will actually look and behave in practice. I think that's what should set the direction. Does this change, as proposed, truly provide the best experience for end users?

What I'd ideally like to do is go in front of the UX team and demo the status quo against the current implementation in the patch, and see what folks' opinions are. That would let us remove the "Needs usability review" tag from this issue, and give us a clearer sense of what to do here with regard to implementing it in core or contrib.

Let me also clarify why I'm hesitant about this: the problem with reusing the source field label and description is that they're not context-sensitive. While they might make perfect, intuitive sense to end users when displayed on, say, a /media/add/whatever form, they might be nonsensical and confusing when seen in the context of the media library modal. The "does it make sense in context?" question is also important from an accessibility standpoint.

So obviously, one thing we could do is make the media library-facing label and description configurable, maybe by adding a third-party setting to the media type. I'd be amenable to that, but I'm not aware of any reason why such a thing couldn't or shouldn't be done in contrib. Adding it to core means giving the site builder even more things to think about when creating media types, and increases the media system's maintenance burden. If the core UX is already reasonable (as determined by the UX team), that's an even stronger reason to put it in contrib.

There are several reasons we have a custom file field in the media library. Most important, the purpose of the file field in the library is a bit different from the purpose of file field in a media source. The library allows multiple items (if the media reference field does) while the media item itself mostly allows only a single file. It also magically creates 1 or more media items after uploading, while the upload field in the media item itself doesn't. For that reason I don't think you can generically say the source field label and description are better and suitable. I don't think there is a one-size-fits-all solution here. I guess the label and description could also depend on the media reference field. The upload field label for a header image might be different from the upload field label of a banner, even though they both use the image media type/source.

That being said, being able to optimise the field label/description for your users/use-case is very helpful. So I agree that you should somehow be able fix that. Technically, you can already change it using a form alter. Not sure if that is good enough?

I would personally say if the form alter is not good enough and we want to have UI for this, we could try to add settings to the media library widget in https://www.drupal.org/project/media_library_extras and see if that works for everyone? Although you would technically need to be able to configure a label and description for every implementation of AddFormBase. Which could be a pain to manage and confusing to configure.

Although you would technically need to be able to configure a label and description for every implementation of AddFormBase. Which could be a pain to manage and confusing to configure.

Having looked at grep.xnddx.ru, I think most implementations of AddFormBase tend to follow predictable patterns which we can detect with a reasonably smart form alter. It wouldn't be foolproof, but I think it would catch most cases. Media Library Extras could also provide a small API for more exotic subclasses of AddFormBase to use.

> Let me also clarify why I'm hesitant about this: the problem with reusing the source field label and description is that they're not context-sensitive. While they might make perfect, intuitive sense to end users when displayed on, say, a /media/add/whatever form, they might be nonsensical and confusing when seen in the context of the media library modal. The "does it make sense in context?" question is also important from an accessibility standpoint.

If that's the case, then is it even safe to use that field out of context in the modal form?

If that's the case, then is it even safe to use that field out of context in the modal form?

Not sure I understand what you mean here. As @seanB pointed out, we don't use the source field in the modal form (we do use it under the hood, but we don't present it to the user). The field that appears in the modal form isn't used anywhere else that I know of. Its very specific purpose is to add some number of media items in the specialized, stripped-down context of the media library. It's fundamentally different from the source field of a single media item.

I see the UX benefits and there are potential assistive tech benefits by it providing a more specific field name to rotors. My main concerns on adding this to core would not be an issue if this was done when Media Library was experimental. Adding it now seems potentially disruptive to existing sites making good use of Media Library. The naming strategy employed my site builders could be potentially very different if they were aware the names would be visible within the media library dialog. Depending on the naming, I could see this change not just being confusing, but perceived by some users as something wrong with the site.
At the very least, it would need to be opt-in as I think it's too potentially jarring a change for existing sites. That said, were this feature opt-in, I'm unsure how many sites would know to even switch it on as it may just be a new element in a form that is easily tuned out, and adoption would potentially be more likely in contrib as it would be driven by users specifically seeking the feature.

The Needs Review Queue Bot tested this issue. It either no longer applies to Drupal core, or fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

Apart from a re-roll or rebase, this issue may need more work to address feedback in the issue or MR comments. To progress an issue, incorporate this feedback as part of the process of updating the issue. This helps other contributors to know what is outstanding.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Re-roll patch for 10.2.x.

Fix PHPCS errors

Hi,
I verified and tested the Patch #37 on the Drupal 11. x version.
Patch applied successfully

Testing steps:

1. Install the Drupal version 11. x
2. Add Media and Media Library Module
3. Go to Structure > Content types -> Add Media field for any content type and save
4. Go to Add Content -> click on Add Media -> select different media options
5. check for the label; it's not changing for different media
6. Apply Patch, again check for the same

Test Result:
When selecting different types of media, that particular media is displayed as a Label

Attaching screenshots for reference

Moving to RTBC

The patch is failing automated tests, unfortunately. It can’t be committed until they all pass… :(

Test fails with errors like No space left on device which seems related to a CIT infrastructure problem.

Not sure what we can do to solve this.

Added standard IS template.

I have reviewed the content and confirmed that it presents the name and description for audio document, image and video media.

I was mildly surprised that it did not also update the name at `media/add/audio`, `media/add/video`, etc, but I can understand why it wasn't. The same information is visible elsewhere on the page.

We discussed this issue at #3531329: Drupal Usability Meeting 2025-06-27. That issue has a link to a recording of the meeting. For the record, the attendees at the usability meeting were @benjifisher and @rkoller.

I plan to leave another comment summarizing that meeting, but until then you can watch the recording.

Usability review

Issue summary updates

I added the tag for an issue summary update. The purpose of the issue summary is to help anyone reviewing the issue understand the proposed changes, and the current summary does not do a good job of that.

1. The Problem/Motivation should be something like this: "When a user uploads a file to a Media reference field, there is not enough context to tell the user what kind of file is expected (audio, image, etc.)." The current text is basically the same as the Proposed Resolution.
2. The issue summary should be very clear about what the "source field" means: the file field on the media entity. This detail is mentioned in passing under the "User interface changes" section, but it should be more prominent and more explicit. This detail is important for understanding the Proposed Resolution.
3. The Steps to reproduce (STR) should be more explicit, so that they lead to a consistent state. The Umami demo profile is good for this sort of thing. My STR are typically something like this:
   
   1. Install Drupal with the Umami demo profile.
   2. Edit field_media_document at Administration > Structure > Media types > Edit Document > Manage fields (/en/admin/structure/media/manage/document/fields). For testing purposes, add something under "Help text".
   3. Edit field_media_image at Administration > Structure > Content types > Article > Manage fields (/en/admin/structure/types/manage/article/fields). Under Media type, select all options.
   4. Create a new Article node (/en/node/add/article). Use the "Add media" button to open the modal editing window, and select Document from the vertical tabs.
4. The screenshots in the User interface changes section should be based on the last step of the STR, and they should show the Help text (description) added in the earlier step.
5. Some part of the issue summary, perhaps Problem/Motivation, should compare the file upload field that does not have enough context to the form at /en/media/add/document, which does have more context (the field label and description mentioned in this issue). This comparison will help avoid confusion, point out where the label and description are currently shown, and point out the inconsistency between the two forms.

Proposed resolution

There were only two people present at the Usability meeting, so these recommendations have less weight than if it had been a larger meeting.

We considered various goals of the proposed changes:

1. Provide better context for the user uploading a file.
2. Be more consistent between the forms at /en/node/add/article and /en/media/add/document.
3. Avoid having more interface text than necessary. ("Less is more.")

The current proposal helps with (1), but goes in the wrong direction for (2). Furthermore, we felt that adding the description (Help text) to the existing field description made it easy to miss.

Instead of replacing the standard "Add field" label with the source field’s label, we feel that a better solution is to add the source field’s label and description above the add-file widget. Explicitly, we suggest something like the following:

Source field label (probably as an <h2> element) Example: Document

Source field description (maybe as a <p> element) Example: This is the help text for the Document field (for the sake of example).

Add file

...

We feel that this provides better context, since the description, if any, is more prominent. (To be clear, less is more: the default description is empty, and site builders should leave it that way unless there is something useful to put there.) We feel this increases consistency between the two forms, since the other one already has the field label as the summary of a <details> element. The drawback is that our suggestion fails the "less is more" test, but we feel that the other points make up for that.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

Re #49

Actioned 1, 2 and 3.

Re 4 - This is already the case, is it not? It shows before and after of 2 media types, one with help text for the last step of the new STR.

5. I believe is covered now.

The current proposal helps with (1), but goes in the wrong direction for (2).

How does it go in the wrong direction? It's directly matching the media add form?

Instead of replacing the standard "Add field" label with the source field’s label, we feel that a better solution is to add the source field’s label and description above the add-file widget.

This was suggested in a previous iteration of this issue I believe. IMO this is adding more noise and going against goal 3 you mentioned.

Adding the description to the existing description (file upload help) matches other UIs such as the media/add form.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Rebased, test failures seems unrelated.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Probably for UX team to decide but should it be "Add Image File"?

Add Image File

No because media can be non-images too. The existing "Add file(s)" label is only used when the field doesn't have a label (basically just a safe guard).

Hey all, I had to make a minor change to patch #37 to adjust for one of the tests in the latest version of Drupal 11.3.5 to get it to apply. I'll work on getting a MR but in the meantime wanted to share the file for anyone who might need it.

3111630-59-media-library-label-and-description.patch

Regarding the UX conversation around whether to include something like this in core, it seemed like the commentary spun a little from how I read the problem statement but the main problem for our users is that if you update the Help Text for a field under Structure > Medias Type > Edit Media Item -> Help Text, that value does not get propagated to the Media Library Upload Widget when uploading Media Items from the Content Editor, whereas it does show from the dedicated upload page.

I've provided screenshots illustrating the problem statement for our users as it seems to be a simple one that the patch solves.

1.) Add Custom Help Text to a media field

2.) Verify the Help Text is showing on the Upload Media Page for that Media Type

3.) Compare that to the Help Text for uploading a file when using the Media Library Upload Widget from editing a Content item.

If I understand the questions correctly, the suggestion turned into having two different fields to represent that Help Text (description) and Title for the static page and the dynamic media library. That seems to be overkill for customization as both the Label and Description should work for all representations of the field to upload something. Any additional clarifying text should likely be appended to that base if it needs to be customized.

Thank you to everyone for their engagement with this issue and I look forward to seeing the resolution of this!

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Bot rebellion

The Usability team discussed this issue at #3585350: Drupal Usability Meeting 2026-04-24. That issue has a link to a recording of the meeting. I am giving issue credit here to the attendees at the usability meeting: @benjifisher, @pallavi singh3013, @rkoller, @simohell, and @worldlinemine.

We were not able to make much progress because it has been months since any of us looked at this issue, and the issue summary still does not make it easy to understand the proposed changes. For now, instead of making recommendations on the proposed resolution, I am updating the issue description:

1. The screenshots show help text for the Video media type, so in the steps to reproduce (STR) I say to add help text for field_media_video_file instead of field_media_document.
2. The screenshots show vertical tabs for three Media types, so I am editing the STR to be consistent.
3. In the "Problem/Motivation" section, I am clarifying that this issue is about the modal form when adding a Media item to an entity, not the dedicated form at /media/add/[type].
4. In the "Problem/Motivation" section, I am emphasizing the two proposed changes: the label and the description.

These changes are in line with what I requested in Comment #49. I think the changes I am making now implicitly answer some of the questions in Comment #50.