Skip to content

Image caption isn't associated to the image in an accessible way #2055

@Ovgodd

Description

@Ovgodd

Is your feature request related to a problem? Please describe.
When adding a caption to an image in BlockNote, the caption currently fails to meet WCAG criterion
The issue is that the caption is not semantically associated with its image.

Expected behavior
The <figure> element should wrap both the <img> and its caption (<figcaption>), ensuring a proper semantic relationship.

Describe the solution you'd like

  • Use <figure> and <figcaption> for images with captions.
  • If a caption is present:
    • Apply the caption as the alt text for the image.
    • Keep the <figcaption> as visible content.
  • If no caption is present:
    • Use an empty alt="".
    • Mark the image as decorative with role="presentation" and aria-hidden="true".

Describe alternatives you've considered

  • Keeping the <p> caption: rejected, as it does not satisfy WCAG requirements.
  • Using aria-describedby: possible fallback, but less semantic than the <figure>/<figcaption> solution.

Additional context
Actual structure :

Image

Example of expected structure:

<figure class="bn-file-block-content-wrapper" role="img" aria-label="Image: Example caption">
  <img src="..." alt="Example caption" />
  <figcaption class="bn-file-caption">Example caption</figcaption>
</figure>

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions