From b8d02537a6c9f534aa1748ef5fcbf8aeea168637 Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Tue, 20 Dec 2022 18:44:33 -0500
Subject: [PATCH] add grouping example

---
 docs/components/select.md              | 31 +++++++++++++++++++++++++-
 src/components/select/select.styles.ts |  8 +++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/components/select.md b/docs/components/select.md
index efe937b9..51f482e5 100644
--- a/docs/components/select.md
+++ b/docs/components/select.md
@@ -286,7 +286,36 @@ TODO
 
 ### Grouping Options
 
-TODO
+Use `<sl-divider>` to group listbox items visually. You can also use `<small>` to provide labels, but they won't be announced by most assistive devices.
+
+```html preview
+<sl-select>
+  <small>Section 1</small>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-divider></sl-divider>
+  <small>Section 2</small>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
+  </SlSelect>
+);
+```
 
 ### Sizes
 
diff --git a/src/components/select/select.styles.ts b/src/components/select/select.styles.ts
index 14f27455..4323eef7 100644
--- a/src/components/select/select.styles.ts
+++ b/src/components/select/select.styles.ts
@@ -244,7 +244,15 @@ export default css`
     max-height: var(--auto-size-available-height);
   }
 
+  /* Slotted content */
   .select__listbox::slotted(sl-divider) {
     --spacing: var(--sl-spacing-x-small);
   }
+
+  .select__listbox::slotted(small) {
+    font-size: var(--sl-font-size-small);
+    font-weight: var(--sl-font-weight-semibold);
+    color: var(--sl-color-neutral-500);
+    padding: var(--sl-spacing-x-small) var(--sl-spacing-x-large);
+  }
 `;