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

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions