From b40266ca90e72778487ff1cb404320c61ce7eb24 Mon Sep 17 00:00:00 2001
From: Joey Arhar <jarhar@chromium.org>
Date: Tue, 28 May 2024 18:02:56 -0700
Subject: [PATCH] Add checkmark to select explainer

Fixes https://github.com/openui/open-ui/issues/863
---
 site/src/pages/components/selectlist.mdx | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/site/src/pages/components/selectlist.mdx b/site/src/pages/components/selectlist.mdx
index 30773f59..ba7e544a 100644
--- a/site/src/pages/components/selectlist.mdx
+++ b/site/src/pages/components/selectlist.mdx
@@ -540,6 +540,15 @@ When the listbox is open:
 
 The HTML parser will not allow `<button>` or `<datalist>` children when the `multiple` or `size` attributes are present on `<select>`. This will ensure that the old rendering behavior of `multiple` and `size` is used. If the author adds a `<datalist>` or `<button>` via script to a `<select multiple>` or `<select size>`, the old rendering will still be used. In the future, we would like to upgrade `<select multiple>` to become stylable, at which time we will change the HTML parser again to allow `<button>` and `<datalist>` children. This also allows feature detection to know whether `<select multiple>` improvements are ready to be used. More detail in [this issue](https://github.com/openui/open-ui/issues/977#issuecomment-1910874971).
 
+## Checkmark
+
+A checkmark is included next to the option elements by default in order to visually indicate which option is currently selected. This improves accessibility/usability because selection doesn't follow focus. You can opt out of rendering the checkmark with the following css:
+```css
+option::before {
+  display: none;
+}
+```
+
 ## Design decisions
 
 - [Why reuse `<select>` instead of creating a new element](https://github.com/openui/open-ui/issues/970)
@@ -555,3 +564,4 @@ The HTML parser will not allow `<button>` or `<datalist>` children when the `mul
 - Why opt-in with CSS
   - https://github.com/whatwg/html/issues/9799#issuecomment-1789202391
   - https://github.com/whatwg/html/issues/9799#issuecomment-1926411811
+- [Why include a checkmark next to options by default](https://github.com/openui/open-ui/issues/863)