[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 23, 2026 5:29pm UTC
blocknote-website	Ready	Preview	Oct 23, 2026 5:29pm 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

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 139d0de8-1fba-4633-84c8-b0827c2ae14c

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.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://TypeCellOS.github.io/BlockNote/pr-preview/pr-3223/
Built to branch gh-pages at 2026-10-23 17:33 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@3223

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@3223

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@3223

@blocknote/diagram-block

npm i https://pkg.pr.new/@blocknote/diagram-block@3223

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@3223

@blocknote/math-block

npm i https://pkg.pr.new/@blocknote/math-block@3223

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@3223

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@3223

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@3223

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@3223

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@3223

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@3223

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@3223

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@3223

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@3223

@blocknote/xl-typst-exporter

npm i https://pkg.pr.new/@blocknote/xl-typst-exporter@3223

commit: a124c3b