Details Block: Fix keyboard accessibility issues and allow list view selection to show up inner blocks

[yogeshbhutkar]

What, Why, and How?

Closes #70047

This PR enhances keyboard interaction with the Details block, enabling users to expand inner blocks using the keyboard. It also fixes a bug that previously prevented selecting an inner block from the List View; clicking an inner block in the List View now correctly selects it in the editor canvas.

With this PR, pressing the down arrow key expands the inner blocks within the Details block, while pressing the up arrow key collapses them.

Testing Instructions

1. Create a post and add the following block markup.

Code

<!-- wp:paragraph -->
<p>First Paragraph Block</p>
<!-- /wp:paragraph -->

<!-- wp:details -->
<details class="wp-block-details">
<summary>Details Block Summary</summary>
<!-- wp:paragraph {"placeholder":"Type / to add a hidden block"} -->
<p>Details Block Content</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>Details Block Content</p>
<!-- /wp:paragraph -->
</details>
<!-- /wp:details -->

<!-- wp:paragraph -->
<p>Second Paragraph Block</p>
<!-- /wp:paragraph -->

2. Try moving through the blocks with the arrow keys.
3. Confirm, the inner blocks within details are accessible using the keyboard.
4. Open the list view and expand the details block.
5. Confirm that clicking on an inner block within the list view opens and selects the inner block properly.

Screencast

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @armandovias.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: armandovias.

Co-authored-by: yogeshbhutkar <[email protected]>
Co-authored-by: Mamaduka <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: alexstine <[email protected]>
Co-authored-by: joedolson <[email protected]>
Co-authored-by: megane9988 <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Mamaduka]

Adding handlers for arrow keys introduces a new behavior for details, which is expanded using Space or Enter keys. Are we okay with this? It would be good to get a11y feedback on this PR before it's merged. cc @joedolson

P.S. I think @t-hamano was also working on this issue.

[alexstine]

@yogeshbhutkar Thanks for working on this.

@Mamaduka We need a way to expand the details block because it isn't currently possible in the editor with the keyboard alone. Give it a test on current trunk, not sure how anyone allowed a regression like this to slip by without keyboard testing. Seems like only way is the mouse at this point.

[yogeshbhutkar]

On a separate note, while spacebar toggling makes sense on the front end, it disrupts the editing experience (I understand it's the default behavior). Disabling this behavior when typing in the summary's rich text would be better. I'd appreciate any accessibility feedback on this.

Observe, pressing the spacebar while typing toggles the hidden content, which could be confusing for users in the editor.

[alexstine]

@yogeshbhutkar Yes, absolutely. If you can detect focus in the summary rich text, space keyboard event needs to be prevented for expand/collapse.

[t-hamano]

Thanks for the PR! The approach that uses keyboard events to collapse or expand the content is an interesting approach.

The only concern is that the summary text can span multiple lines. In this case, the content is toggled every time you move from one line to another can be annoying.

Another approach I can think of may be using the Enter key. Additionally, let screenreader users know the details block was toggled by the speak() method. In other words, the code would be like this:

<summary
	onKeyDown={ ( event ) => {
		if ( event.key === 'Enter' && ! event.shiftKey ) {
			setIsOpen( ! isOpen );
			event.preventDefault();
		}
	} }
>

Finally, I think we also need to add some e2e tests to avoid regressions.

[t-hamano]

Another thing to note is that in CJK languages, an IME (Input Method Editor) is used to input complex characters.

There is a higher-order function to ignore keyboard events during IME composition. We will probably need to wrap keydown events in this function in your Details block as well.

See the following PRs for more details:

• Components: Add HOF to ignore IME keydowns #59081
• InputControl: Ignore IME events when isPressEnterToChange #60090

[alexstine]

That looks good @t-hamano. Shift enter will insert new line while enter will expand/collapse. I'm not overly thrilled with the UX but it is 100% better than trunk today. Also, can we fix the list view here as well? Any time a hidden block is selected, auto-expand the summary?

Thanks.

[t-hamano]

@alexstine

Also, can we fix the list view here as well? Any time a hidden block is selected, auto-expand the summary?

I think you can confirm that this issue has already been fixed in this PR. This is because when an inner block is selected in the List View, hasSelectedInnerBlock is true and the open attribute of the details element is true:

https://github.com/WordPress/gutenberg/pull/70056/files#diff-20d83620db8197c679e5617a73e78de6306074dff49588bb00fd5ee35a17793bR105

[joedolson]

This looks like it's progressing well; thanks for getting on this! I think that you all have this well in hand, but if you need a 2nd review once everything is ready, let me know.

[alexstine]

This is working much better indeed. For sure need to do something about the expanding content though. If I insert a new line with enter and then down arrow to it, all I hear is expanded. So I do like the idea of shift+enter to insert a new line, enter will trigger expand/collapse, and arrows should navigate the content only.

[t-hamano]

Thanks for the update, @yogeshbhutkar!

I think this PR is going pretty well.

Any time a hidden block is selected, auto-expand the summary?

Can we add an e2e test for this? The steps should be like this:

• Insert a Details block
• Open the List view
• Press the right arrow key: The inner blocks of the Details block are displayed in the List View
• Press the down arrow key: The first inner block is focused in the List View
• Press the enter key: The first inner block should be focused in the editor canvas

[t-hamano]

@WordPress/gutenberg-components

We export this HOF as a private API. We need this function in the block library to prevent the Details content from being toggled by the Enter key event fired by the IME event.

[t-hamano]

Update: Let's test whether it works without this HOF.

[t-hamano]

Update: If the HOF is not used, unintended events occur in the IME and it does not work properly (See #70056 (comment)). Therefore, it is necessary to use HOF as a private API.

[megane9988]

I tested it.

OS: macOS 15.4.1（24E263）
Browser: Chrome 135.0.7049.115
IME: Google 日本語入力 ( https://www.google.co.jp/ime/ )

Test Steps

• Adding a Details Block
• Pressing the Enter key on the Summary text should toggle the content open and closed.
• Pressing Enter + Shift on the Summary text should insert a line break without toggling the content.
• Key operations while inputting Japanese (such as the Enter key and Space key) should be ignored, and the content should not toggle.

2025-05-08.13.35.24.mov

It worked well.

[megane9988]

I tested it.

OS: macOS 15.4.1（24E263）
Browser: Safari 18.4 (20621.1.15.11.10)
IME: Google 日本語入力 ( https://www.google.co.jp/ime/ )

Test Steps

• Adding a Details Block
• Pressing the Enter key on the Summary text should toggle the content open and closed.
• Pressing Enter + Shift on the Summary text should insert a line break without toggling the content.
• Key operations while inputting Japanese (such as the Enter key and Space key) should be ignored, and the content should not toggle.

2025-05-08.14.01.21.mov

It also worked well.

[megane9988]

I also tested using ことえり ( macOS default IME ) in both browsers (Chrome and Safari).
It also worked well.

2025-05-08.14.10.21.mov

[yogeshbhutkar]

I've incorporated all the feedback. A few follow-ups for the details block (separate from this PR):

1. We should add e2e coverage for drag-and-drop, as it previously caused a regression and remains a risk.

2. Keyboard navigation should also be possible when the block is collapsed. As of now, hidden blocks restrict the movement, and removing them might not be good for accessibility.

3. When inserting inner blocks, only the first shows the correct / placeholder (Type / to add a hidden block). Subsequent ones revert to the default. We should persist the template message while adding hidden blocks to avoid confusion. Coming out of details requires double enter, but the editor screen shows no feedback. Plus, if we are adding a hidden block, the message should always state so.

I'd like to know the opinion of others on this.

[yogeshbhutkar]

Based on the test results, I think it's best to at least wrap the keydown handler function. The space would always work because it technically just prevents the default behavior; therefore, no abnormalities can be seen in the editor.

What do you think, @t-hamano?

[t-hamano]

Thank you so much for testing, @megane9988!

I think it's best to at least wrap the keydown handler function.

@yogeshbhutkar Yes, based on his tests, it would be enough to apply HOF only to the keydown handler. Sorry for the frequent suggestions for changes.

[t-hamano]

LGTM! Before shipping this PR, let's get some accessibility feedback again.

[alexstine]

@yogeshbhutkar This is looking much better. One final thought. Since it isn't clear that the details can be expanded, maybe add aria-describedby with some basic instructions?

Press Enter to toggle details child blocks.

The expanded/collapsed state does enough to notify users of the exposed content, nice job on that.

I also agree it would be nice to do something about the "hidden" in the new block placeholder phrasing. The block isn't technically hidden if the details element is expanded.

Thanks.

[yogeshbhutkar]

Thanks for the feedback, @alexstine.

I've implemented the suggested feedback. When you have a moment, could you please re-review the changes and approve them if everything looks good?

[alexstine]

@yogeshbhutkar Can you add the aria-describedby to the input rich text field, not the block wrapper? If you press Enter from the block wrapper, you will insert a new block, not expand the element.

It also seems like something has changed where the Up/Down arrow keys can now toggle the display and this can be rather disruptive as Up/Down arrow keys allow screen reader users to read by line.

Thanks.

[alexstine]

I'm not sure if RichText can take aria-describedby by default, hopefully so. I would also like to see if anyone else can reproduce the Up/Down arrow keys toggling the state of the hidden blocks while in the summary edit field.

[alexstine]

This cannot be defined here as pressing Enter at block wrapper level will insert a new block, not expand/collapse the summary.

[yogeshbhutkar]

Thanks! I've moved this to RichText and verified that the message now triggers correctly when typing in the RichText field.

[yogeshbhutkar]

I would also like to see if anyone else can reproduce the Up/Down arrow keys toggling the state of the hidden blocks while in the summary edit field.

I tested this and wasn't able to toggle the hidden blocks using the arrow keys; only the Enter key worked, as expected. I've attached a screencast for reference.

cc: @alexstine

Edit: I tested this in Chrome, Firefox, and Safari, but wasn't able to replicate it in any of them. Can you provide a screencast, as it might help me investigate this further?

test.mov

[t-hamano]

Adding the VisuallyHidden component inside the summary element seems to add unexpected focus.

For example, add a Details block to the top and focus on the post title. The screen reader will read it as follows:

1. Press the down key: Block: Details document blank
2. Press the down key: Press Enter to expand or collapse the details. Summary Text button collapsed 1 of 1
3. Press the down key: Write summary edit multi line Press Enter to expand or collapse the details. Summary Text

f0cada83bb7812ce11991158704f4d82.mp4

A second focus should not be necessary.

I would suggest that since the RichText component already has an aria-label, we just add the text there.

diff --git a/packages/block-library/src/details/edit.js b/packages/block-library/src/details/edit.js
index a21a00bade..c2df5721e9 100644
--- a/packages/block-library/src/details/edit.js
+++ b/packages/block-library/src/details/edit.js
@@ -130,14 +130,11 @@ function DetailsEdit( { attributes, setAttributes, clientId } ) {
                                        onKeyDown={ withIgnoreIMEEvents( handleSummaryKeyDown ) }
                                        onKeyUp={ handleSummaryKeyUp }
                                >
-                                       <VisuallyHidden id={ instanceId }>
-                                               { __(
-                                                       'Press Enter to expand or collapse the details.'
-                                               ) }
-                                       </VisuallyHidden>
                                        <RichText
                                                identifier="summary"
-                                               aria-label={ __( 'Write summary' ) }
+                                               aria-label={ __(
+                                                       'Write summary. Press Enter to expand or collapse the details.'
+                                               ) }
                                                aria-describedby={ instanceId }
                                                placeholder={ placeholder || __( 'Write summary…' ) }
                                                withoutInteractiveFormatting

So the screen reader should read something like this:

1. Press the down key: Block: Details document blank
2. Press the down key: Write summary. Press Enter to expand or collapse the details. edit multi line Summary Text

I would also like to see if anyone else can reproduce the Up/Down arrow keys toggling the state of the hidden blocks while in the summary edit field.

In the first state of this PR, we were using the up and down arrow keys.
But now we're using the enter key to toggle the content, so I think this issue is no longer a problem.