Editorial review: Document customizable <select> elements #38470

chrisdavidmills · 2025-03-05T18:09:15Z

Description

Chrome 134 supports customizable <select> elements (see https://chromestatus.com/feature/5737365999976448).

This includes a multitude of sub-features, which are as follows:

The <selectedcontent> element mirrors the currently-selected <option> contents. This is the content visible inside the closed <select> element, otherwise known as the select <button>.
The ::picker(select) pseudo-element, which targets the entire contents of the select drop-down menu, otherwise known as the picker.
The appearance property value base-select, which opts the <select> element and the ::picker(select) pseudo-element into the browser-defined default styles and behavior for customizable select.
The :open pseudo-class, which can now target the select <button> when the picker (::picker(select)) is open.
The ::picker-icon pseudo-element, which targets the picker icon inside the select <button> — the little down-facing arrow on the inline-end side.
The :checked pseudo-class, which can now target the currently-selected <option> element.
The ::checkmark pseudo-element, which targets the checkmark placed inside the currently-selected <option> element to provide a visual indication of which one is selected.

In addition, the select <button> and the picker have the following behavior assigned to them automatically:

They have an invoker/popover relationship, as specified by the Popover API.
They have an implicit anchor reference, meaning that the picker is automatically positioned relative to the select <button> via CSS anchor positioning.

This PR aims to document all of the above new/updated features, and:

provide a guide to creating customizable <select>s.

Motivation

Additional details

Related issues and pull requests

Fixes #37857

BCD: mdn/browser-compat-data#26171

github-actions · 2025-03-05T18:11:17Z

Preview URLs (30 pages)

Flaws (40)

Note! 16 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes
Title: UI pseudo-classes
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/void_element is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/void_element which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls
Title: Other form controls
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/void_element is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/void_element which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data
Title: Sending form data
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/submit_button is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/submit_button which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls
Title: Basic native form controls
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/void_element is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/void_element which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types
Title: The HTML5 input types
Flaw count: 2

broken_links:
- /en-US/docs/Web/API/validityState/typeMismatch is ill cased
macros:
- Macro produces link /en-US/docs/Web/API/validityState/typeMismatch which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form
Title: Your first form
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/void_element is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/void_element which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript
Title: Sending forms through JavaScript
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/progressive_web_apps is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/progressive_web_apps which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls
Title: How to build custom form controls
Flaw count: 6

broken_links:
- /en-US/docs/Web/API/element/classList is ill cased
- /en-US/docs/Web/API/element/querySelector is ill cased
- /en-US/docs/Web/API/element/querySelectorAll is ill cased
macros:
- Macro produces link /en-US/docs/Web/API/element/classList which is a redirect
- Macro produces link /en-US/docs/Web/API/element/querySelector which is a redirect
- Macro produces link /en-US/docs/Web/API/element/querySelectorAll which is a redirect

URL: /en-US/docs/Learn_web_development/Extensions/Forms/HTML_forms_in_legacy_browsers
Title: HTML forms in legacy browsers
Flaw count: 1

unknown:
- No generic content config found

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select
Title: Customizable select elements
Flaw count: 3

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Can't resolve /en-US/docs/Web/CSS/@starting-state

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API
Flaw count: 8

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/inset_properties is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/HTML/Element/button
Title: <button>: The Button element
Flaw count: 4

broken_links:
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/accessible_name is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/accessible_name which is a redirect

URL: /en-US/docs/Web/HTML/Element/select
Title: <select>: The HTML Select element
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/user_agent is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect

URL: /en-US/docs/Web/CSS/CSS_anchor_positioning/Using
Title: Using CSS anchor positioning
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect

External URLs (85)

URL: /en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes
Title: UI pseudo-classes

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls
Title: Other form controls

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data
Title: Sending form data

https://developer.chrome.com/docs/devtools/ (1 time)
https://en.wikipedia.org/wiki/SQL (1 time)
https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html (1 time)
https://flask.palletsprojects.com/ (2 times)
https://getlaminas.org/ (1 time)
https://github.com/web2py/web2py (1 time)
https://httpd.apache.org/ (1 time)
https://infosec.mozilla.org/guidelines/web_security (1 time)
https://jinja.palletsprojects.com/ (1 time)
https://laravel.com/ (1 time)
https://mdn.github.io/learning-area/html/forms/sending-form-data/get-method.html (1 time)
https://mdn.github.io/learning-area/html/forms/sending-form-data/post-method.html (1 time)
https://nextjs.org/ (1 time)
https://nginx.org/ (1 time)
https://nuxt.com/ (1 time)
https://owasp.org/ (1 time)
https://py4web.com/ (1 time)
https://remix.run/ (1 time)
https://rubyonrails.org/ (1 time)
https://spring.io/guides/gs/handling-form-submission/ (1 time)
https://symfony.com/ (1 time)
https://tomcat.apache.org/ (1 time)
https://www.apachefriends.org/download.html (1 time)
https://www.iis.net/ (1 time)
https://www.mamp.info/en/downloads/ (1 time)
https://www.php.net/ (1 time)

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls
Title: Basic native form controls

URL: /en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types
Title: The HTML5 input types

https://mdn.github.io/learning-area/html/forms/basic-input-examples/ (1 time)

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form
Title: Your first form

URL: /en-US/docs/Learn_web_development/Extensions/Forms/Form_validation
Title: Client-side form validation

URL: /en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls
Title: How to build custom form controls

https://addons.mozilla.org/fr/firefox/addon/noscript/ (1 time)
https://chromewebstore.google.com/detail/scriptblock/hcdjknjpbnhdoabbngpmfekaecnpajba (1 time)
https://en.wikipedia.org/wiki/Usability_testing (1 time)
https://github.com/marghoobsuleman/ms-Dropdown (1 time)
https://jqueryui.com/ (1 time)
https://www.apple.com/accessibility/vision/ (1 time)
https://www.nvaccess.org/ (1 time)
https://www.smashingmagazine.com/ (1 time)
https://www.uxmatters.com/ (1 time)
https://www.w3.org/TR/wai-aria/ (1 time)
https://www.webaxe.org/accessible-custom-select-dropdowns/ (1 time)

URL: /en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form
Title: How to structure a web form

URL: /en-US/docs/Learn_web_development/Extensions/Forms/HTML_forms_in_legacy_browsers
Title: HTML forms in legacy browsers

URL: /en-US/docs/Web/API/HTMLSelectedContentElement
Title: HTMLSelectedContentElement

https://github.com/whatwg/html/pull/10633 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTML/Element/selectedcontent
Title: <selectedcontent>: The selected option display element

https://github.com/whatwg/html/pull/10633 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-03-10 17:16:57)

… unneeded links

files/en-us/web/html/element/selectedcontent/index.md

hamishwillee

@chrisdavidmills I have gone through this, but was exhausted by the end, so might have got sloppy. There's a lot here - looks good.

One thing that I don't think was covered is the stuff in the explainer around default aria stuff. Might not be needed, but worth a quick re-read to see if there is something to be said.

The ::checkmark pseudo-element has its contents populated via the content property. The value of the content property can have an additional argument provided to set the accessible name, which we currently set to an empty string by default to hide it from the a11y tree. The value isn't important because I think the checked state of the option element is already provided in a different way, and announcing a checkmark icon is not helpful. Based on this discussion, we should do this by default for the ::checkmark pseudo without requiring the author to also set the accessible name to the empty string: mdn/content#38470 (comment) Fixed: 405946933 Change-Id: I983b1e7dff879f2c1a2184c505046d0581f93380 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6388535 Reviewed-by: Aaron Leventhal <[email protected]> Commit-Queue: Aaron Leventhal <[email protected]> Cr-Commit-Position: refs/heads/main@{#1437677}

files/en-us/web/css/pseudo-elements/index.md

files/en-us/learn_web_development/extensions/forms/customizable_select/index.md

hamishwillee

@chrisdavidmills Thanks for this. I've reviewed your fixes and I think they are good. Added a few more comments but I don't want to block you merging this when you have looked at them so approving.

Note, I didn't look in detail at everything again. There is a lot here and many eyes have been over it.

I believe all those issues have been addressed.

chrisdavidmills · 2025-03-28T13:42:05Z

@chrisdavidmills Thanks for this. I've reviewed your fixes and I think they are good. Added a few more comments but I don't want to block you merging this when you have looked at them so approving.

Nice one @hamishwillee — thanks for the excellent review!

…, a=testonly Automatic update from web-platform-tests Don't make a11y mappings for ::checkmark The ::checkmark pseudo-element has its contents populated via the content property. The value of the content property can have an additional argument provided to set the accessible name, which we currently set to an empty string by default to hide it from the a11y tree. The value isn't important because I think the checked state of the option element is already provided in a different way, and announcing a checkmark icon is not helpful. Based on this discussion, we should do this by default for the ::checkmark pseudo without requiring the author to also set the accessible name to the empty string: mdn/content#38470 (comment) Fixed: 405946933 Change-Id: I983b1e7dff879f2c1a2184c505046d0581f93380 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6388535 Reviewed-by: Aaron Leventhal <[email protected]> Commit-Queue: Aaron Leventhal <[email protected]> Cr-Commit-Position: refs/heads/main@{#1437677} -- wpt-commits: 02363c922be2f833803a8bd2150a7b18c57192d2 wpt-pr: 51585

hamishwillee · 2025-03-30T22:29:10Z

Yay!

…, a=testonly Automatic update from web-platform-tests Don't make a11y mappings for ::checkmark The ::checkmark pseudo-element has its contents populated via the content property. The value of the content property can have an additional argument provided to set the accessible name, which we currently set to an empty string by default to hide it from the a11y tree. The value isn't important because I think the checked state of the option element is already provided in a different way, and announcing a checkmark icon is not helpful. Based on this discussion, we should do this by default for the ::checkmark pseudo without requiring the author to also set the accessible name to the empty string: mdn/content#38470 (comment) Fixed: 405946933 Change-Id: I983b1e7dff879f2c1a2184c505046d0581f93380 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6388535 Reviewed-by: Aaron Leventhal <[email protected]> Commit-Queue: Aaron Leventhal <[email protected]> Cr-Commit-Position: refs/heads/main@{#1437677} -- wpt-commits: 02363c922be2f833803a8bd2150a7b18c57192d2 wpt-pr: 51585

* Document customizable <select> elements * fix typo * Finish guide * correct info about how <selectedcontent> is populated * add links to customizable select guide, update existing pages, remove unneeded links * Document selectedcontent element * Add doc for ::picker() * Document appearance: base-select, tweak :open and :checked ref pages * Document the ::picker-icon and ::checkmark pseudos * Add notes on implicit popover-invoker relationship and anchor reference * Add default picker styling info, tweak other info * Fixes for josepharhar review comments * Fixes for josepharhar review comments * Fixes for scottaohara review comments * Accessibility and <select> content fixes * Additional fixes * Additional fixes * Additional fixes * Fixes for hamishwillee review comments * Change other elements back to other content * Last few tweaks from hamishwillee review

…, a=testonly Automatic update from web-platform-tests Don't make a11y mappings for ::checkmark The ::checkmark pseudo-element has its contents populated via the content property. The value of the content property can have an additional argument provided to set the accessible name, which we currently set to an empty string by default to hide it from the a11y tree. The value isn't important because I think the checked state of the option element is already provided in a different way, and announcing a checkmark icon is not helpful. Based on this discussion, we should do this by default for the ::checkmark pseudo without requiring the author to also set the accessible name to the empty string: mdn/content#38470 (comment) Fixed: 405946933 Change-Id: I983b1e7dff879f2c1a2184c505046d0581f93380 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6388535 Reviewed-by: Aaron Leventhal <[email protected]> Commit-Queue: Aaron Leventhal <[email protected]> Cr-Commit-Position: refs/heads/main@{#1437677} -- wpt-commits: 02363c922be2f833803a8bd2150a7b18c57192d2 wpt-pr: 51585

* Document customizable <select> elements * fix typo * Finish guide * correct info about how <selectedcontent> is populated * add links to customizable select guide, update existing pages, remove unneeded links * Document selectedcontent element * Add doc for ::picker() * Document appearance: base-select, tweak :open and :checked ref pages * Document the ::picker-icon and ::checkmark pseudos * Add notes on implicit popover-invoker relationship and anchor reference * Add default picker styling info, tweak other info * Fixes for josepharhar review comments * Fixes for josepharhar review comments * Fixes for scottaohara review comments * Accessibility and <select> content fixes * Additional fixes * Additional fixes * Additional fixes * Fixes for hamishwillee review comments * Change other elements back to other content * Last few tweaks from hamishwillee review

Document customizable <select> elements

4e4b77c

chrisdavidmills requested a review from a team as a code owner March 5, 2025 18:09

chrisdavidmills requested review from hamishwillee and removed request for a team March 5, 2025 18:09

chrisdavidmills marked this pull request as draft March 5, 2025 18:09

github-actions bot added Content:Learn Learning area docs size/m [PR only] 51-500 LoC changed labels Mar 5, 2025

chrisdavidmills added 5 commits March 5, 2025 18:12

fix typo

db40b51

Finish guide

e55d318

Merge branch 'main' into customizable-select

fd5ecff

correct info about how <selectedcontent> is populated

029cb9d

add links to customizable select guide, update existing pages, remove…

80b9f67

… unneeded links

github-actions bot added Content:HTML Hypertext Markup Language docs size/l [PR only] 501-1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Mar 7, 2025

Document selectedcontent element

9998430

github-actions bot added the Content:WebAPI Web API docs label Mar 7, 2025

Add doc for ::picker()

4dc3040

github-actions bot added the Content:CSS Cascading Style Sheets docs label Mar 10, 2025

chrisdavidmills added 4 commits March 10, 2025 11:06

Document appearance: base-select, tweak :open and :checked ref pages

edbc2b1

Document the ::picker-icon and ::checkmark pseudos

afdbacb

Add notes on implicit popover-invoker relationship and anchor reference

28e9f6e

Merge branch 'main' into customizable-select

c33195c

chrisdavidmills marked this pull request as ready for review March 10, 2025 13:18

chrisdavidmills requested review from a team as code owners March 10, 2025 13:18

chrisdavidmills requested review from dipikabh and removed request for a team March 10, 2025 13:18

hamishwillee reviewed Mar 25, 2025

View reviewed changes

files/en-us/web/html/element/selectedcontent/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Mar 25, 2025

View reviewed changes

files/en-us/web/html/element/selectedcontent/index.md Show resolved Hide resolved

hamishwillee reviewed Mar 25, 2025

View reviewed changes

files/en-us/web/html/element/selectedcontent/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Mar 25, 2025

View reviewed changes

Fixes for hamishwillee review comments

10bfb9c

chrisdavidmills requested a review from hamishwillee March 25, 2025 12:37

chromium-wpt-export-bot mentioned this pull request Mar 25, 2025

Don't make a11y mappings for ::checkmark web-platform-tests/wpt#51585

Merged

Change other elements back to other content

c230327

hamishwillee reviewed Mar 28, 2025

View reviewed changes

files/en-us/web/css/pseudo-elements/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Mar 28, 2025

View reviewed changes

files/en-us/learn_web_development/extensions/forms/customizable_select/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Mar 28, 2025

View reviewed changes

files/en-us/learn_web_development/extensions/forms/customizable_select/index.md Outdated Show resolved Hide resolved

hamishwillee approved these changes Mar 28, 2025

View reviewed changes

Last few tweaks from hamishwillee review

7655bb3

chrisdavidmills requested a review from a team as a code owner March 28, 2025 13:41

Merge branch 'main' into customizable-select

64fe9e4

chrisdavidmills merged commit 2595b22 into mdn:main Mar 28, 2025
8 checks passed

chrisdavidmills deleted the customizable-select branch March 28, 2025 13:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Editorial review: Document customizable <select> elements #38470

Editorial review: Document customizable <select> elements #38470

Uh oh!

chrisdavidmills commented Mar 5, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Mar 5, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hamishwillee left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hamishwillee left a comment

Uh oh!

chrisdavidmills commented Mar 28, 2025

Uh oh!

Uh oh!

hamishwillee commented Mar 30, 2025

Uh oh!

Uh oh!

Editorial review: Document customizable <select> elements #38470

Editorial review: Document customizable <select> elements #38470

Uh oh!

Conversation

chrisdavidmills commented Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hamishwillee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hamishwillee left a comment

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented Mar 28, 2025

Uh oh!

Uh oh!

hamishwillee commented Mar 30, 2025

Uh oh!

Uh oh!

chrisdavidmills commented Mar 5, 2025 •

edited

Loading

github-actions bot commented Mar 5, 2025 •

edited

Loading