Skip to content

chore: add documentation on accessibility of custom fields #9807

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rachel-fenichel wants to merge 3 commits into
base: v13
Choose a base branch
from
Open

chore: add documentation on accessibility of custom fields #9807

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
83a976a
chore: add accessibility section for extending a built-in field
rachel-fenichel May 1, 2026
89c49ce
chore: add information about accessibility to the creating a custom f…
rachel-fenichel May 1, 2026
33ce4c7
chore(docs): better phrasing about getAriaValue
rachel-fenichel May 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 45 additions & 10 deletions ...es/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ To create a new field, do the following:
1. [Handle disposal of event listeners](#disposing) (UI disposal is handled for
you).
1. [Implement value handling](#value-handling).
1. [Add a text-representation of your field's value, for accessibility](#text).
1. [Add a text-representation of your field's value](#text).
1. Add additional functionality such as:
- [An editor](#creating-an-editor).
- [On-block display updates](#updating-the-on-block-display).
Expand Down Expand Up @@ -166,6 +166,25 @@ The requirements of a field's on-block display are:
- All DOM elements must be children of the field's `fieldGroup_`. The field
group is created automatically.
- All DOM elements must stay inside the reported dimensions of the field.
- The root DOM element has an appropriate
[ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques).


### Accessibility

You are responsible for ensuring that your custom fields are WCAG compliant and
correctly implement `IFocusableNode`. That includes having an appropriate ARIA
role for your on-block display and making your field editor WCAG compliant.

In general, the on-block display for a clickable field should have the ARIA
role `button` to indicate that an action will take place when it is clicked or
activated.
Copy link
Copy Markdown
Contributor

@mikeharv mikeharv May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the only example because it's known to the most common?

Copy link
Copy Markdown
Collaborator Author

@rachel-fenichel rachel-fenichel May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Are there other roles that you think are worth including? Checkbox is the only other one that came to mind.


When the on-block display is focused, its focusable DOM element will have the
`blocklyActiveFocus` or `blocklyPassiveFocus` CSS class added. Blockly defaults
to showing a yellow outline around the focused field. You may override this
behaviour as long as you show [visible focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html).


See the
[Rendering](/guides/create-custom-blocks/fields/customizing-fields/creating#updating-the-on-block-display)
Expand All @@ -180,11 +199,13 @@ field's degree symbol) you can append the symbol element (usually contained in a

### Input events

By default fields register tooltip events, and mousedown events (to be used for
showing
[editors](/guides/create-custom-blocks/fields/customizing-fields/creating#creating-an-editor)).
If you want to listen for other kinds of events (e.g. if you want to handle
dragging on a field) you should override the field's `bindEvents_` function.
By default fields register tooltip events, mousedown events, and some keyboard
events. Users can open the field
[editor](/guides/create-custom-blocks/fields/customizing-fields/creating#creating-an-editor)
by tapping or clicking on the field, or by navigating to the field with the
keyboard and pressing `Enter`. If you want to listen for other kinds of events
(e.g. if you want to handle dragging on a field) you should override the field's
`bindEvents_` function.

```js
bindEvents_() {
Expand Down Expand Up @@ -424,12 +445,26 @@ getText() {
}
```

All fields must have an ARIA type and value, which are used to construct the
ARIA label. The ARIA label is generally of the form `<ARIA type>: <ARIA value>`.
The ARIA value defaults to the result of calling `getText` on the field. You
must ensure that the result is meaningful when read with a screen reader. To
this end, if getAriaValue returns an invalid representation (i.e. `null` or
empty string) then it should be instead represented using a localization of the
text empty string to convey this to the user.
Copy link
Copy Markdown
Contributor

@mikeharv mikeharv May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Add quotes around "empty string" for clarity?

Copy link
Copy Markdown
Collaborator Author

@rachel-fenichel rachel-fenichel May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to match the phrasing you suggested for extending a field.


## Creating an editor

If you define the `showEditor_` function, Blockly will automatically listen for
clicks and call `showEditor_` at the appropriate time. You can display any HTML
in your editor by wrapping it one of two special `div`s, called the
`DropDownDiv` and `WidgetDiv`, which float above the rest of Blockly's UI.
If you define the `showEditor_` function, Blockly will automatically call
`showEditor_` and move focus into the editor when the field is activated.
You can display any HTML in your editor by wrapping it one of two special
`div`s, called the `DropDownDiv` and `WidgetDiv`, which float above the rest of
Blockly's UI.

You are responsible for the accessibility of your field editor, including
setting [ARIA roles and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques).
When possible you should use [semantic HTML](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/HTML)
inside the `WidgetDiv` or `DropdownDiv`.

:::info
Updates to an editor's display should be handled during
Expand Down
25 changes: 25 additions & 0 deletions ...s/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,3 +72,28 @@ static fromJson(options) {

For more information about registering a field see the [JSON and registration](/guides/create-custom-blocks/fields/customizing-fields/creating#json-and-registration)
section in Creating a Custom Field.

## Accessibility

You are responsible for ensuring that your custom fields are WCAG compliant and
correctly implement `IFocusableNode`. That includes having an appropriate
[ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques)
for your on-block display and making your field editor WCAG compliant.

When the on-block display is focused, its focusable DOM element will have the
`blocklyActiveFocus` or `blocklyPassiveFocus` CSS class added. Blockly defaults
to showing a yellow outline around the focused field. You may override this
behaviour as long as you show [visible focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html).

All fields must have an ARIA type and value, which are used to construct the
[ARIA label](/guides/create-custom-blocks/fields/anatomy-of-a-field#aria-label).
The ARIA label is generally of the form `<ARIA type>: <ARIA value>`. The ARIA
value defaults to the result of calling `getText` on the field. You must ensure
that the result is meaningful when read with a screen reader. To this end, if
`getAriaValue` returns an invalid representation (i.e. `null` or empty string)
then it should be instead represented using a localization of the text
`empty string` to convey this to the user.
Copy link
Copy Markdown
Contributor

@mikeharv mikeharv May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is all factual, but I feel like we could make it a bit clearer. The word "it" on line 94 is particularly ambiguous, but I think we could generally tighten the responsibility here too:

getAriaValue must return a human-readable, screen reader–appropriate representation of the field’s current value. By default, it returns the result of getText, which is not guaranteed to be informative for assistive technologies.
You must override getAriaValue when getText might not produce a meaningful spoken representation (for example, when possible values includes symbols, abbreviations, or non-textual representations such as icons or colors).
If getAriaValue would return an empty or non-informative value, it must instead return a localized string indicating that the value is empty.

Copy link
Copy Markdown
Collaborator Author

@rachel-fenichel rachel-fenichel May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated.


When extending a built-in field you will inherit its ARIA type and value logic.
You can override the inherited ARIA logic by overriding any of `getAriaTypeName`,
`getAriaValue`, and `computeAriaLabel`.
Copy link
Copy Markdown
Contributor

@mikeharv mikeharv May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, do expect people to need to override computeAriaLabel? It's really just building the <ARIA type>: <ARIA value> string (or just <ARIA value> when type info is excluded). While it's possible to change how this works, I would think most developers would only need to override the other two.

Copy link
Copy Markdown
Contributor

@mikeharv mikeharv May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also wonder if it would be overkill to include an example here of when you might want to override, such as making things more specific... Example: 'Angle' instead of 'Number' for type or n + ' degrees' for clarifying the meaning of the value.

Copy link
Copy Markdown
Collaborator Author

@rachel-fenichel rachel-fenichel May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have any built-in fields that do anything interesting for type or value that I could link to?

Loading