[matthewlipski]

Summary

When the editor is read-only, list item blocks aren't properly announced as being list items or belonging to any list. This PR gives list item blocks the listitem role, and adds a listItem: boolean field to the meta property so custom blocks can be flagged as list items to receive the role automatically. This lets screen readers know that an element is a list item without it being a li element, so the following HTML snippets are equivalent:

<ul>
  <li>
    List item 1
  </li>
  <li>
    List item 2
  </li>
</ul>

<div role="list">
  <p role="listitem">
    List item 1
  </p>
  <p role="listitem">
    List item 2
  </p>
</div>

However, this doesn't fully solve the issue as list item blocks don't share a common ancestor list block/element, so there is no ul/role="list" to group list items by. The way around this is the aria-owns attribute, which tells assistive technologies that an element is semantically the ancestor of some other elements, even though it isn't in the DOM. So the snippet below is also equivalent to the ones above:

<div role="list" aria-owns="list-item-1 list-item-2" />
<p id="list-item-1" role="listitem">
  List item 1
</p>
<p id="list-item-2" role="listitem">
  List item 2
</p>

So this PR also adds a div with aria-owns before each each consecutive string of list item blocks of the same type.

All of what's described above, i.e. setting role & id attributes on list item blocks as well as creating an invisible div with role="list" and aria-owns, is done in the ListAccessibilityExtension via decorations.

The editor role has also been changed from textbox to document when the editor is read-only as the list item changes otherwise cause issues with VoiceOver. This would need further investigation if we wanted to apply this fix always, but #2809 only requires the fix for a read-only editor.

Closes #2809

Rationale

List items are not properly read out by screen readers when the editor is read-only.

Changes

See above.

Impact

N/A

Testing

Updated default document for screen reader tests to also test lists. Screen reader tests remain skipped for the time being. Axe scans do not catch this issue as list item blocks are rendered using p elements, so they are just seen as paragraphs and list item rules don't apply.

Screenshots/Video

For the following editor structure:

<paragraph>Shopping list</paragraph>
<bulletListItem>Apples</bulletListItem>
<bulletListItem>Oranges</bulletListItem>

Below are VoiceOver transcript snippets when announcing the blocks.

Before:

Shopping list
Apples
Oranges Insertion at beginning of text. list box pop-up edit text

The "Insertion at beginning of text. list box pop-up edit text" is due to the editor's textbox role, which announces that the content is editable even though it is not.

After:

Shopping list
list 2 items
Apples 1 of 2
Oranges 2 of 2
end of list

The list items are now properly announced as such, and as being part of the same list.

Checklist

• Code follows the project's coding standards.
• Unit tests covering the new feature have been added.
• All existing tests pass.
• The documentation has been updated to reflect the new feature

Additional Notes

N/A

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blocknote	Ready	Preview	Oct 21, 2026 5:34pm UTC
blocknote-website	Ready	Preview	Oct 21, 2026 5:34pm UTC

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9a439278-088a-49dd-a2f8-41ce2f0743a4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}