A11y: UploadJSXConverter uses filename instead of alt field for image alt attribute

[JeremyEnglert]

Describe the Bug

The UploadJSXConverter in @payloadcms/richtext-lexical uses the file's filename for the image alt attribute instead of the alt field from the upload document.

I'm guessing this is done to because "alt" isn't a required field for media and we want to avoid empty alt tags. But forcing the file name into the alt is a bad practice and also prevents an alt from being placed if the field does exist.

I'd lean towards removing the filename as the alt and only using an alt if the user has a defined alt field.

Link to the code that reproduces this issue

https://github.com/payloadcms/payload

Reproduction Steps

1. Add an alt field to your media collection (or use the default one if present)
2. Upload an image and set a descriptive alt text
3. Insert that image into a rich text field
4. Render the rich text content using the RichText component from @payloadcms/richtext-lexical/react
5. Inspect the rendered tag - the alt attribute contains the filename instead of the alt text

Which area(s) are affected? (Select all that apply)

plugin: richtext-lexical

Environment Info

Binaries:
  Node: 22.19.0
  npm: 10.9.3
  Yarn: N/A
  pnpm: 9.12.3
Relevant Packages:
  payload: 3.63.0
  next: 15.3.2
  @payloadcms/db-mongodb: 3.63.0
  @payloadcms/email-nodemailer: 3.63.0
  @payloadcms/graphql: 3.63.0
  @payloadcms/live-preview: 3.63.0
  @payloadcms/live-preview-react: 3.63.0
  @payloadcms/next/utilities: 3.63.0
  @payloadcms/plugin-cloud-storage: 3.63.0
  @payloadcms/plugin-form-builder: 3.63.0
  @payloadcms/plugin-seo: 3.63.0
  @payloadcms/richtext-lexical: 3.63.0
  @payloadcms/storage-s3: 3.63.0
  @payloadcms/translations: 3.63.0
  @payloadcms/ui/shared: 3.63.0
  react: 19.1.1
  react-dom: 19.1.1
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.4.0: Fri Apr 11 18:33:47 PDT 2025; root:xnu-11417.101.15~117/RELEASE_ARM64_T6000
  Available memory (MB): 16384
  Available CPU cores: 8

[rilrom]

From what I can tell doing this properly would require introducing a breaking change (we'd need to allow the developer the opportunity to set a custom field name for alt text, we cannot assume it will always be named alt). We could do this in a similar manner to how it's handled in LinkJSXConverter.

export const UploadJSXConverter: (args?: {
  altFieldName?: string
}) => JSXConverters<SerializedUploadNode> = ({ altFieldName = 'alt' } = {}) => ({

In the interim, we could just assume the field name is alt and set that directly with a fallback to fieldname. It's not perfect but it's better than what we're currently doing and it will solve the majority of situations as I imagine alt is the most common name for this field.

@paulpopus what do you think?

Edit: this is me assuming that the alt field would flow through from node without too much difficulty.

[paulpopus]

Discussed with German that the best approach here is likely to add alt as a property on the UploadNode directly

Until we get around to doing a PR here just note that you can customise the renderer as needed in your frontend to output a custom field into the alt attribute of your component