feat: a11y testing setup

[matthewlipski]

Summary

This PR shows a vertical slice of the a11y areas we need to test. It's based on the a11y study done earlier. It's recommended to get familiarised with that first. The documents from the study are also temporarily included as Markdown files in the git branch.

The general approach was to colocate a11y test files with the components they test. The tests all require using a browser environment due to one of the following:

1. Test uses axe-core, which requires a real DOM tree to scan.
2. Test uses GuidePup to test screen reader output, which requires a browser to use a screen reader with.
3. Test uses Playwright visual snapshots, which require rendering components in a browser.
4. Test requires browser keyboard navigation/focus handling.

Below is a summary of the tested a11y areas. For each type of test:

🟢 Tests are implemented and passing.
🟡 Tests are implemented and passing, but snapshots are at least partially incorrect.
🔴 Tests aren't implemented as the functionality being tested is missing, or are implemented but failing.

Editor Content

These tests are for making sure the editor content is broadly accessible, covering keyboard navigation, focus handling, legibility, and screen reader support.

BlockNoteView.a11y.spec.ts

• General
  • 🔴 Ensure that running an axe-core check doesn't yield any errors for an editor with a document with content containing everything in the default schema.
    • There are quite a lot of various errors.
• Document keyboard navigation
  • 🟡 Navigate through a document using only the arrow keys, including navigating through each cell in a table. Ensure that additional information e.g. block type/nesting level/etc is announced to the user during navigation, using screen reader transcripts generated by GuidePup.
    • Arrow key navigation works without issues, but a lot of information regarding markup and document structure is missing from screen reader transcripts.
• Focus handling
  • 🟢 Ensure that as the user navigates through interactive elements in a page using Tab, the user can continue immediately to the next element when focus lands on the editor, rather than being trapped within the editor.
    • When the editor is focused, the user can hit Escape to revert focus to <body> and pressing Tab moves focus to the next interactive element in the page. This works for now but will have to be revisited when fixing the selection handling (see below).
• Selection handling
  • 🔴 Ensure that the editor can be focused without a selection, allowing Tab and arrow keys navigate the page rather than navigating the editor.
    • While the user can hit Escape to revert focus to <body>, it's not quite what we want as they cannot e.g. press Enter to then refocus the editor.
  • 🔴 Ensure that the current selection can be extended to wrap the entire block using the keyboard.
    • Selecting entire blocks is possible using Cmd+Click, but not using the keyboard, so only a stub is included for this test.
  • 🔴 Ensure that the type of selection is communicated by a screen reader using transcripts generated by GuidePup.
    • Selecting entire blocks is not possible using the keyboard, so only stubs is included for these tests.
    • TODO: add tests for other selection types (text selection, whole document selection, block without inline content selection).
  • 🔴 Ensure that selection state is communicated visually using Playwright visual snapshots.
    • Selecting entire blocks is not possible using the keyboard, so only stubs is included for these tests.
    • TODO: add tests for other selection types (text selection, whole document selection, block without inline content selection).
• Legibility
  • 🟢 Ensure that all a document with content containing everything in the default schema remains legible and doesn't clip content, when text spacing is overridden to that defined by WCAG 1.4.12 success criteria, using a Playwright visual snapshot.
  • 🟢 Ensure that all a document with content containing everything in the default schema remains legible and doesn't clip content, when text sizing is overridden to that defined by WCAG 1.4.4 success criteria, using a Playwright visual snapshot.

Interactive blocks

These tests are for making sure that for any blocks with interactive elements, e.g. check list items and toggle headings, the interactive elements can be manipulated using the keyboard. Currently, only the check list item has a test file.

block.a11y.spec.ts

• Interactive elements
  • 🔴 For each interactive element in the block, ensure it can be manipulated using the keyboard.
    • Technically, this is possible but it's incredibly obtuse. Things like check list item checkboxes can be focused and toggled but that requires the editor to not be focused. They also mess with the page's tab order and are generally make keyboard navigation a pain.

Editor UI

These tests verify the accessibility of BlockNote's UI elements like menus and toolbars. These cover basically everything a11y related - keyboard navigation, focus handling, legibility, and screen reader support. Currently, only the formatting toolbar is tested, which fortunately has had some a11y improvements already.

FormattingToolbar.a11y.spec.ts

• General
  1. 🔴 Ensure that running an axe-core check on the toolbar doesn't yield any errors.
  2. Ensure that running axe-core check on any drop-downs or other hidden elements doesn't yield any errors.
• Keyboard and focus handling
  1. 🟡 Ensure that the toolbar can be opened and focused using the keyboard, then closed with focus returning to the editor, and that this is correctly communicated by a screen reader using transcripts generated by GuidePup.
  2. 🟢 Ensure that each interactive item in the toolbar can be focused and executed using the keyboard.
  3. 🟡 Ensure that the currently focused item has a focus ring or some other visual cue, using using Playwright visual snapshots.

Rationale

While we have done accessibility work before, it was mainly patching fairly glaring issues like the formatting toolbar being inaccessible via the keyboard. This PR is the start of a longer term commitment to improve a11y, and testing gives us a framework for figuring out where the main issues are and what still needs to be done.

Changes

TODO

Impact

N/A

Testing

See above.

Screenshots/Video

N/A

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

Broader TODOs:

• Currently, keyboard focus/navigation tests for blocks with interactive elements are colocated with the respective blocks. However, screen reader testing for table cells is not colocated with table blocks. Should we even have colocated tests for specific blocks, or should we clump them into editor content tests since they're part of the default schema?
• Screen reader tests are expensive. They are valuable, but more for identifying potential improvements rather than regressions. Do we want/need all of the ones included in this PR?
• CI is technically implemented but I haven't looked into it very deep so it most likely needs work.
• We should revisit existing unit and e2e tests for UI elements and keyboard handling. We are likely implicitly testing a bunch of things through keyboard navigation that have dedicated unit tests. Should be done in a separate PR though.
• We should enable the a11y oxlint rules, but that's out of scope for this PR.

[vercel]

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

Project	Deployment	Actions	Updated
blocknote	Ready	Preview	Oct 9, 2026 4:38pm UTC
blocknote-website	Ready	Preview	Oct 9, 2026 4:38pm UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

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

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

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

@blocknote/code-block

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

@blocknote/core

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

@blocknote/diagram-block

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

@blocknote/mantine

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

@blocknote/math-block

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

@blocknote/react

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

@blocknote/server-util

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

@blocknote/shadcn

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

@blocknote/xl-ai

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

@blocknote/xl-docx-exporter

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

@blocknote/xl-email-exporter

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

@blocknote/xl-multi-column

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

@blocknote/xl-odt-exporter

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

@blocknote/xl-pdf-exporter

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

@blocknote/xl-typst-exporter

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

commit: 35b14f2

[github-actions]

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