@aurodesignsystem/auro-formkit 5.9.0 → 5.9.2

package/components/select/demo/api.md

@@ -1,49 +1,45 @@
-<!--
-The apiExamples.md file is a compiled document. No edits should be made directly to this file.
-
-apiExamples.md is created by running `npm run build:markdownDocs`.
-
-This file is generated based on a template fetched from `./docs/partials/apiExamples.md`
--->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/api.md) -->
 <!-- The below content is automatically added from ./../docs/api.md -->
 
 # auro-select
 
-The auro-select element is a wrapper for auro-dropdown and auro-menu to create a dropdown menu control.
+The `auro-select` element is a wrapper for auro-dropdown and auro-menu to create a dropdown menu control.
 
 ## Properties
 
-| Property                        | Attribute                       | Type                              | Default        | Description                                      |
-|---------------------------------|---------------------------------|-----------------------------------|----------------|--------------------------------------------------|
-| [appearance](#appearance)                    | `appearance`                    | `string`                          | "'default'"    | Defines whether the component will be on lighter or darker backgrounds. |
-| [autoPlacement](#autoPlacement)                 | `autoPlacement`                 | `boolean`                         | "false"        | If declared, bib's position will be automatically calculated where to appear. |
-| [autocomplete](#autocomplete)                  | `autocomplete`                  | `string`                          |                | If declared, sets the autocomplete attribute for the select element. |
-| [disabled](#disabled)                      | `disabled`                      | `boolean`                         |                | When attribute is present, element shows disabled state. |
-| [error](#error)                         | `error`                         | `string`                          |                | When defined, sets persistent validity to `customError` and sets `setCustomValidity` = attribute value. |
-| [fluid](#fluid)                         | `fluid`                         | `boolean`                         |                | When attribute is present, element will be 100% width of container element. |
-| [forceDisplayValue](#forceDisplayValue)             | `forceDisplayValue`             | `boolean`                         | false          | If declared, the label and value will be visually hidden and the displayValue will render 100% of the time. |
-| [fullscreenBreakpoint](#fullscreenBreakpoint)          | `fullscreenBreakpoint`          | `string`                          | "sm"           | Defines the screen size breakpoint (`xs`, `sm`, `md`, `lg`, `xl`, `disabled`)<br />at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
-| [largeFullscreenHeadline](#largeFullscreenHeadline)       | `largeFullscreenHeadline`       | `boolean`                         |                | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
-| [layout](#layout)                        |                                 | `string`                          |                |                                                  |
-| [matchWidth](#matchWidth)                    | `matchWidth`                    | `boolean`                         | false          | If declared, the popover and trigger will be set to the same width. |
-| [multiSelect](#multiSelect)                   | `multiselect`                   | `boolean`                         |                | Sets multi-select mode, allowing multiple options to be selected at once. |
-| [name](#name)                          | `name`                          | `string`                          |                | The name for the select element.                 |
-| [noCheckmark](#noCheckmark)                   | `noCheckmark`                   | `boolean`                         |                | When true, checkmark on selected option will no longer be present. |
-| [noFlip](#noFlip)                        | `noFlip`                        | `boolean`                         | "false"        | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
-| [noValidate](#noValidate)                    | `noValidate`                    | `boolean`                         |                | If set, disables auto-validation on blur.        |
-| [offset](#offset)                        | `offset`                        | `number`                          | "0"            | Gap between the trigger element and bib.         |
-| [onDark](#onDark)                        | `onDark`                        | `boolean`                         |                | DEPRECATED - use `appearance` instead.           |
-| [optionSelected](#optionSelected)                | `optionSelected`                | `HTMLElement\|Array<HTMLElement>` |                | Specifies the current selected menuOption. Default type is `HTMLElement`, changing to `Array<HTMLElement>` when `multiSelect` is true. |
-| [placeholder](#placeholder)                   | `placeholder`                   | `string`                          |                | Define custom placeholder text.                  |
-| [placement](#placement)                     | `placement`                     | `string`                          | "bottom-start" | Position where the bib should appear relative to the trigger.<br />Accepted values:<br />"top" \| "right" \| "bottom" \| "left" \|<br />"bottom-start" \| "top-start" \| "top-end" \|<br />"right-start" \| "right-end" \| "bottom-end" \|<br />"left-start" \| "left-end". |
-| [required](#required)                      | `required`                      | `boolean`                         |                | Populates the `required` attribute on the element. Used for client-side validation. |
-| [setCustomValidity](#setCustomValidity)             | `setCustomValidity`             | `string`                          |                | Sets a custom help text message to display for all validityStates. |
-| [setCustomValidityCustomError](#setCustomValidityCustomError)  | `setCustomValidityCustomError`  | `string`                          |                | Custom help text message to display when validity = `customError`. |
-| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `string`                          |                | Custom help text message to display when validity = `valueMissing`. |
-| [shift](#shift)                         | `shift`                         | `boolean`                         | "false"        | If set, the dropdown will shift its position to avoid being cut off by the viewport. |
-| [validity](#validity)                      | `validity`                      | `string`                          |                | Specifies the `validityState` this element is in. |
-| [value](#value)                         | `value`                         | `string`                          |                | Value selected for the component.                |
+| Property                        | Attribute                       | Type                                             | Default          | Description                                      |
+|---------------------------------|---------------------------------|--------------------------------------------------|------------------|--------------------------------------------------|
+| [appearance](#appearance)                    | `appearance`                    | `'default' \| 'inverse'`                         | "'default'"      | Defines whether the component will be on lighter or darker backgrounds. |
+| [autoPlacement](#autoPlacement)                 | `autoPlacement`                 | `boolean`                                        | false            | If declared, bib's position will be automatically calculated where to appear. |
+| [autocomplete](#autocomplete)                  | `autocomplete`                  | `string`                                         |                  | If declared, sets the autocomplete attribute for the select element. |
+| [disabled](#disabled)                      | `disabled`                      | `boolean`                                        |                  | When attribute is present, element shows disabled state. |
+| [error](#error)                         | `error`                         | `string`                                         |                  | When defined, sets persistent validity to `customError` and sets `setCustomValidity` = attribute value. |
+| [flexMenuWidth](#flexMenuWidth)                 | `flexMenuWidth`                 | `boolean`                                        |                  | If declared, make the width of the bib match the width of the content, rather than the trigger. |
+| [fluid](#fluid)                         | `fluid`                         | `boolean`                                        |                  | When attribute is present, element will be 100% width of container element. |
+| [forceDisplayValue](#forceDisplayValue)             | `forceDisplayValue`             | `boolean`                                        | false            | If declared, the label and value will be visually hidden and the displayValue will render 100% of the time. |
+| [fullscreenBreakpoint](#fullscreenBreakpoint)          | `fullscreenBreakpoint`          | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'"           | Defines the screen size breakpoint at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
+| [largeFullscreenHeadline](#largeFullscreenHeadline)       | `largeFullscreenHeadline`       | `boolean`                                        |                  | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
+| [layout](#layout)                        | `layout`                        | `'classic' \| 'emphasized' \| 'snowflake'`       | "'classic'"      | Determines the overall layout of the select component. |
+| [matchWidth](#matchWidth)                    | `matchWidth`                    | `boolean`                                        | false            | If declared, the popover and trigger will be set to the same width. |
+| [multiSelect](#multiSelect)                   | `multiselect`                   | `boolean`                                        |                  | Sets multi-select mode, allowing multiple options to be selected at once. |
+| [name](#name)                          | `name`                          | `string`                                         |                  | The name for the select element.                 |
+| [noCheckmark](#noCheckmark)                   | `noCheckmark`                   | `boolean`                                        |                  | When true, checkmark on selected option will no longer be present. |
+| [noFlip](#noFlip)                        | `noFlip`                        | `boolean`                                        | false            | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
+| [noValidate](#noValidate)                    | `noValidate`                    | `boolean`                                        |                  | If set, disables auto-validation on blur.        |
+| [offset](#offset)                        | `offset`                        | `number`                                         | "0"              | Gap between the trigger element and bib.         |
+| [onDark](#onDark)                        | `onDark`                        | `boolean`                                        |                  | DEPRECATED - use `appearance="inverse"` instead. |
+| [optionSelected](#optionSelected)                | `optionSelected`                | `HTMLElement\|Array<HTMLElement>`                |                  | Specifies the current selected menuOption. Default type is `HTMLElement`, changing to `Array<HTMLElement>` when `multiSelect` is true. |
+| [placeholder](#placeholder)                   | `placeholder`                   | `string`                                         |                  | Define custom placeholder text.                  |
+| [placement](#placement)                     | `placement`                     | `'top' \| 'right' \| 'bottom' \| 'left' \| 'bottom-start' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-end' \| 'left-start' \| 'left-end'` | "'bottom-start'" | Position where the bib should appear relative to the trigger. |
+| [required](#required)                      | `required`                      | `boolean`                                        |                  | Populates the `required` attribute on the element. Used for client-side validation. |
+| [setCustomValidity](#setCustomValidity)             | `setCustomValidity`             | `string`                                         |                  | Sets a custom help text message to display for all validityStates. |
+| [setCustomValidityCustomError](#setCustomValidityCustomError)  | `setCustomValidityCustomError`  | `string`                                         |                  | Custom help text message to display when validity = `customError`. |
+| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `string`                                         |                  | Custom help text message to display when validity = `valueMissing`. |
+| [shape](#shape)                         | `shape`                         | `'classic' \| 'pill' \| 'pill-left' \| 'pill-right' \| 'snowflake'` |                  | Determines the shape of the dropdown bib.        |
+| [shift](#shift)                         | `shift`                         | `boolean`                                        | false            | If set, the dropdown will shift its position to avoid being cut off by the viewport. |
+| [size](#size)                          | `size`                          | `'lg' \| 'xl'`                                   |                  | Determines the size of the dropdown bib. Only the `emphasized` layout supports size=`xl`, while all other layouts support size=`lg`. |
+| [validity](#validity)                      | `validity`                      | `string`                                         |                  | Specifies the `validityState` this element is in. |
+| [value](#value)                         | `value`                         | `string`                                         |                  | Value selected for the component.                |
 
 ## Methods
 
@@ -81,16 +77,12 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 | Part              | Description                                      |
 |-------------------|--------------------------------------------------|
 | [dropdownChevron](#dropdownChevron) | Apply CSS to the collapsed/expanded state icon container. |
-| [dropdownSize](#dropdownSize)    | Apply size styles to the dropdown bib. (height, width, maxHeight, maxWidth only) |
+| [dropdownSize](#dropdownSize)    | Apply size styles to the dropdown bib (height, width, maxHeight, maxWidth only). |
 | [dropdownTrigger](#dropdownTrigger) | Apply CSS to the trigger content container.      |
 | [helpText](#helpText)        | Apply CSS to the help text.                      |
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## API Examples
-
-### Default example
-
-A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements.
+## Basic
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
@@ -110,23 +102,6 @@ A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements.
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
-<div class="exampleWrapper--ondark" aria-hidden>
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearance.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/inverseAppearance.html -->
-  <auro-select appearance="inverse">
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Select Example</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
@@ -148,93 +123,55 @@ A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements.
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearance.html) -->
-<!-- The below content is automatically added from ./../apiExamples/inverseAppearance.html -->
-<auro-select appearance="inverse">
-  <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Select Example</span>
-  <auro-menu>
-    <auro-menuoption value="stops">Stops</auro-menuoption>
-    <auro-menuoption value="price">Price</auro-menuoption>
-    <auro-menuoption value="duration">Duration</auro-menuoption>
-    <auro-menuoption value="departure">Departure</auro-menuoption>
-    <auro-menuoption value="arrival">Arrival</auro-menuoption>
-    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-  </auro-menu>
-</auro-select>
-<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Property Examples
+## Property & Attribute Examples
 
-#### value <a name="value"></a>
-Use the `value` property to define a preset value on the `auro-select` element. The `value` of `auro-select` must match the `value` defined of a single `auro-menuoption`. Upon initially rendering the component, if the `value` does not match an `auro-menuoption`, the `value` of `auro-select` will be set to `undefined`.
+### Appearance on Dark Backgrounds
 
-To pre-set the value of auro-select on load, use the `value` property. The `selected` attribute on auro-menuoption is designed to illustrate state in the DOM.
+Use the `appearance="inverse"` attribute to render the component for use on dark backgrounds.
 
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/value.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/value.html -->
-  <auro-button id="validValueExampleBtn">Set Value to Valid Option</auro-button>
-  <auro-button id="invalidValueExampleBtn">Set Value to Invalid Option</auro-button>
-  <br/><br/>
-  <auro-select id="valueExample" multiselect value='["price", "duration"]'>
+<div class="exampleWrapper--ondark">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/appearance-inverse.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/appearance-inverse.html -->
+  <auro-select appearance="inverse">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Name</span>
+    <span slot="label">Select Example</span>
     <auro-menu>
-      <auro-menuoption id="option-0" value="stops">Stops</auro-menuoption>
-      <auro-menuoption id="option-1" value="price">Price</auro-menuoption>
-      <auro-menuoption id="option-2" value="duration">Duration</auro-menuoption>
-      <auro-menuoption id="option-3" value="departure">Departure</auro-menuoption>
-      <auro-menuoption id="option-4" value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption id="option-5" value="prefer alaska">Prefer Alaska</auro-menuoption>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
     </auro-menu>
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/value.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/appearance-inverse.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/appearance-inverse.html -->
 
 ```html
-<auro-button id="validValueExampleBtn">Set Value to Valid Option</auro-button>
-<auro-button id="invalidValueExampleBtn">Set Value to Invalid Option</auro-button>
-<br/><br/>
-<auro-select id="valueExample" multiselect value='["price", "duration"]'>
+<auro-select appearance="inverse">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Name</span>
+  <span slot="label">Select Example</span>
   <auro-menu>
-    <auro-menuoption id="option-0" value="stops">Stops</auro-menuoption>
-    <auro-menuoption id="option-1" value="price">Price</auro-menuoption>
-    <auro-menuoption id="option-2" value="duration">Duration</auro-menuoption>
-    <auro-menuoption id="option-3" value="departure">Departure</auro-menuoption>
-    <auro-menuoption id="option-4" value="arrival">Arrival</auro-menuoption>
-    <auro-menuoption id="option-5" value="prefer alaska">Prefer Alaska</auro-menuoption>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
   </auro-menu>
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/value.js -->
-
-```js
-export function valueExample() {
-  const valueExample = document.querySelector('#valueExample');
-
-  document.querySelector('#validValueExampleBtn').addEventListener('click', () => {
-    valueExample.value = '["arrival", "prefer alaska"]';
-  });
-
-  document.querySelector('#invalidValueExampleBtn').addEventListener('click', () => {
-    valueExample.value = '["flight course"]';
-  });
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### Autocomplete <a name="autocomplete"></a>
+### Autocomplete
+
 Use the `autocomplete` attribute to let browser's know what information to use to fill out the form.
 
 <div class="exampleWrapper">
@@ -407,18 +344,17 @@ Use the `autocomplete` attribute to let browser's know what information to use t
   </div>
 </div>
 ```
-<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### required <a name="required"></a>
-When present, the `required` attribute specifies that a select field must be filled out before submitting the form.
+### Disabled
 
-When the validity check fails the validityState, equals `valueMissing`. The error message for the `valueMissing` validityState can be set to a custom string using the `setCustomValidityValueMissing`. There is no default error message defined.
+Use the `disabled` attribute to toggle the disabled UI.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/required.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/required.html -->
-  <auro-select required setCustomValidityValueMissing="Custom required validation error message." placeholder="Placeholder Text">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/disabled.html -->
+  <auro-select disabled placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
     <auro-menu>
@@ -431,14 +367,14 @@ When the validity check fails the validityState, equals `valueMissing`. The erro
     </auro-menu>
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/required.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/required.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/disabled.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/disabled.html -->
 
 ```html
-<auro-select required setCustomValidityValueMissing="Custom required validation error message." placeholder="Placeholder Text">
+<auro-select disabled placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
   <span slot="label">Label</span>
   <auro-menu>
@@ -453,17 +389,12 @@ When the validity check fails the validityState, equals `valueMissing`. The erro
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
-
-### Custom optional label <a name="optionalLabel"></a>
-The `<auro-select>` supports an `optionalLabel` slot, where users can can override the default `(optional)` notification text.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/optionalLabel.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/optionalLabel.html -->
-  <auro-select>
+<div class="exampleWrapper--ondark">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/appearance-inverse-disabled.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/appearance-inverse-disabled.html -->
+  <auro-select appearance="inverse" disabled placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Please select a preference</span>
-    <span slot="optionalLabel" style="color: grey; font-size: small"> - optional</span>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -477,14 +408,11 @@ The `<auro-select>` supports an `optionalLabel` slot, where users can can overri
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/optionalLabel.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/optionalLabel.html -->
-
-```html
-<auro-select>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/appearance-inverse-disabled.html) -->
+<!-- The below content is automatically added from ./../apiExamples/appearance-inverse-disabled.html -->
+<auro-select appearance="inverse" disabled placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Please select a preference</span>
-  <span slot="optionalLabel" style="color: grey; font-size: small"> - optional</span>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -493,13 +421,13 @@ The `<auro-select>` supports an `optionalLabel` slot, where users can can overri
     <auro-menuoption value="arrival">Arrival</auro-menuoption>
     <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
   </auro-menu>
-</auro-select>
-```
+</auro-select>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### error <a name="error"></a>
-Use the `error` boolean attribute to toggle the error UI.
+### Error
+
+Use the `error` attribute to toggle the error UI.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/error.html) -->
@@ -518,23 +446,6 @@ Use the `error` boolean attribute to toggle the error UI.
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
-<div class="exampleWrapper--ondark" aria-hidden>
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceError.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/inverseAppearanceError.html -->
-  <auro-select appearance="inverse" error="Custom error message" placeholder="Placeholder Text">
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Label</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/error.html) -->
@@ -555,47 +466,11 @@ Use the `error` boolean attribute to toggle the error UI.
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceError.html) -->
-<!-- The below content is automatically added from ./../apiExamples/inverseAppearanceError.html -->
-<auro-select appearance="inverse" error="Custom error message" placeholder="Placeholder Text">
-  <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Label</span>
-  <auro-menu>
-    <auro-menuoption value="stops">Stops</auro-menuoption>
-    <auro-menuoption value="price">Price</auro-menuoption>
-    <auro-menuoption value="duration">Duration</auro-menuoption>
-    <auro-menuoption value="departure">Departure</auro-menuoption>
-    <auro-menuoption value="arrival">Arrival</auro-menuoption>
-    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-  </auro-menu>
-</auro-select>
-<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
-
-#### disabled <a name="disabled"></a>
-Use the `disabled` boolean attribute to toggle the disabled UI.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/disabled.html -->
-  <auro-select disabled placeholder="Placeholder Text">
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Label</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
 <div class="exampleWrapper--ondark" aria-hidden>
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceDisabled.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/inverseAppearanceDisabled.html -->
-  <auro-select appearance="inverse" disabled placeholder="Placeholder Text">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/appearance-inverse-error.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/appearance-inverse-error.html -->
+  <auro-select appearance="inverse" error="Custom error message" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
     <auro-menu>
@@ -611,27 +486,9 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/disabled.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/disabled.html -->
-
-```html
-<auro-select disabled placeholder="Placeholder Text">
-  <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Label</span>
-  <auro-menu>
-    <auro-menuoption value="stops">Stops</auro-menuoption>
-    <auro-menuoption value="price">Price</auro-menuoption>
-    <auro-menuoption value="duration">Duration</auro-menuoption>
-    <auro-menuoption value="departure">Departure</auro-menuoption>
-    <auro-menuoption value="arrival">Arrival</auro-menuoption>
-    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceDisabled.html) -->
-<!-- The below content is automatically added from ./../apiExamples/inverseAppearanceDisabled.html -->
-<auro-select appearance="inverse" disabled placeholder="Placeholder Text">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/appearance-inverse-error.html) -->
+<!-- The below content is automatically added from ./../apiExamples/appearance-inverse-error.html -->
+<auro-select appearance="inverse" error="Custom error message" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
   <span slot="label">Label</span>
   <auro-menu>
@@ -646,50 +503,13 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### multiselect <a name="multiselect"></a>
-Sets multi-select mode, allowing multiple options to be selected at once.
+### Flex Menu Width
 
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/multiselect.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/multiselect.html -->
-  <auro-select multiselect>
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Select one or more options</label>
-    <span slot="label">multiselect select example</span>
-    <auro-menu>
-      <auro-menuoption value="1">Option 1</auro-menuoption>
-      <auro-menuoption value="2">Option 2</auro-menuoption>
-      <auro-menuoption value="3">Option 3</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/multiselect.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/multiselect.html -->
-
-```html
-<auro-select multiselect>
-  <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Select one or more options</label>
-  <span slot="label">multiselect select example</span>
-  <auro-menu>
-    <auro-menuoption value="1">Option 1</auro-menuoption>
-    <auro-menuoption value="2">Option 2</auro-menuoption>
-    <auro-menuoption value="3">Option 3</auro-menuoption>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-#### flexMenuWidth <a name="flexMenuWidth"></a>
 Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-select>` element to match the width of the bib content, rather than the width of the trigger.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/flexMenuWidth.html) -->
-  <!-- The below content is automatically added from ../apiExamples/flexMenuWidth.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/flex-menu-width.html) -->
+  <!-- The below content is automatically added from ../apiExamples/flex-menu-width.html -->
   <auro-select flexMenuWidth id="flexMenuWidthExample" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
@@ -710,8 +530,8 @@ Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-sele
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/flexMenuWidth.html) -->
-<!-- The below code snippet is automatically added from ../apiExamples/flexMenuWidth.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/flex-menu-width.html) -->
+<!-- The below code snippet is automatically added from ../apiExamples/flex-menu-width.html -->
 
 ```html
 <auro-select flexMenuWidth id="flexMenuWidthExample" placeholder="Placeholder Text">
@@ -734,17 +554,22 @@ Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-sele
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Slot Examples
-
-#### label <a name="label"></a>
-Use the `label` slot to give your users contextual information about their selection options. This `label` content is also helpful for assistive devices.
+### Dropdown with Fullscreen Bib
+
+You can make the dropdown open in fullscreen at a specific breakpoint by setting `fullscreenBreakpoint`.
 
+The default value of `fullscreenBreakpoint` is `sm`. 
+
+Breakpoint token can be found [here](https://auro.alaskaair.com/getting-started/developers/design-tokens)
+
+To support fullcreen bib, setting `bib.fullscreen.headline` is **STRONGLY RECOMMENDED**.
+
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/label.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/label.html -->
-  <auro-select>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/fullscreen-breakpoint.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/fullscreen-breakpoint.html -->
+  <auro-select fullscreenBreakpoint="lg">
+    <span slot="label">Select Example</span>
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Please select a preference</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -755,16 +580,772 @@ Use the `label` slot to give your users contextual information about their selec
     </auro-menu>
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/label.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/label.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/fullscreen-breakpoint.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/fullscreen-breakpoint.html -->
+
+```html
+<auro-select fullscreenBreakpoint="lg">
+  <span slot="label">Select Example</span>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+#### Disabled Fullscreen Bib
+
+This example overrides the default dropdown behavior to force a non-fullscreen view on any screen size. `disabled`
+ensures that the dropdown will never be fullscreen.
+Please use `xl` if you want the opposite behavior, where a dropdown is always fullscreen.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/fullscreen-disabled.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/fullscreen-disabled.html -->
+  <auro-select fullscreenBreakpoint="disabled">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Select Example</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/fullscreen-disabled.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/fullscreen-disabled.html -->
+
+```html
+<auro-select fullscreenBreakpoint="disabled">
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Select Example</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Shape | Size | Layout Support
+
+The `auro-select` component supports the `shape`, `size` and `layout` feature set. The component defaults to the `layout="classic"`, `shape="classic"` and `size="lg"`.
+
+#### Classic Layout (Legacy)
+
+The `classic` layout is default for `auro-select`. No customization is needed to achieve this look.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/basic.html -->
+  <auro-select>
+    <span slot="ariaLabel.bib.close">Close Popup</span>
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Select Example</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
 
 ```html
 <auro-select>
+  <span slot="ariaLabel.bib.close">Close Popup</span>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Select Example</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+#### Emphasized Layout
+
+The `emphasized` layout is only supported on light backgrounds.
+
+The `emphasized` layout supports the following shapes:
+- `pill`
+- `pill-left`
+- `pill-right`
+
+The `emphasized` layout supports the following sizes:
+- `xl`
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/emphasized/basic.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/emphasized/basic.html -->
+  <div style="display: flex; flex-direction: row; gap: 10px;">
+    <auro-select layout="emphasized" shape="pill" size="xl" value="flights" forceDisplayValue style="display:inline-block;">
+      <span slot="ariaLabel.bib.close">Close Popup</span>
+      <span slot="label">Select Example</span>
+      <auro-menu nocheckmark>
+        <auro-menuoption value="flights">
+          <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="terminal" name="plane-diag-fill" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="cars">
+          <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="car-rental-stroke" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="hotels">
+          <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="hotel-filled" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="packages">
+          <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="shop" name="gift-filled" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="cruises">
+          <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="in-flight" name="boarding" customcolor></auro-icon>
+        </auro-menuoption>
+      </auro-menu>
+    </auro-select>
+    <auro-select layout="emphasized" shape="pill" size="xl" value="flights" style="display:inline-block;">
+      <span slot="label">Select Example</span>
+      <auro-menu nocheckmark>
+        <auro-menuoption value="flights">
+          <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="terminal" name="plane-diag-fill" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="cars">
+          <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="car-rental-stroke" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="hotels">
+          <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="hotel-filled" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="packages">
+          <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="shop" name="gift-filled" customcolor></auro-icon>
+        </auro-menuoption>
+        <auro-menuoption value="cruises">
+          <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+          <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="in-flight" name="boarding" customcolor></auro-icon>
+        </auro-menuoption>
+      </auro-menu>
+    </auro-select>
+    <auro-select layout="emphasized" shape="pill" size="xl" value="flights" required style="display:inline-block;">
+      <span slot="label">Select Example</span>
+      <span slot="helpText">no displayValue in menuoptions</span>
+      <auro-menu nocheckmark>
+        <auro-menuoption value="flights">
+          <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+        </auro-menuoption>
+        <auro-menuoption value="cars">
+          <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+        </auro-menuoption>
+        <auro-menuoption value="hotels">
+          <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+        </auro-menuoption>
+        <auro-menuoption value="packages">
+          <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+        </auro-menuoption>
+        <auro-menuoption value="cruises">
+          <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+        </auro-menuoption>
+      </auro-menu>
+    </auro-select>
+  </div>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/emphasized/basic.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/emphasized/basic.html -->
+
+```html
+<div style="display: flex; flex-direction: row; gap: 10px;">
+  <auro-select layout="emphasized" shape="pill" size="xl" value="flights" forceDisplayValue style="display:inline-block;">
+    <span slot="ariaLabel.bib.close">Close Popup</span>
+    <span slot="label">Select Example</span>
+    <auro-menu nocheckmark>
+      <auro-menuoption value="flights">
+        <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="terminal" name="plane-diag-fill" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="cars">
+        <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="car-rental-stroke" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="hotels">
+        <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="hotel-filled" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="packages">
+        <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="shop" name="gift-filled" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="cruises">
+        <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="in-flight" name="boarding" customcolor></auro-icon>
+      </auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <auro-select layout="emphasized" shape="pill" size="xl" value="flights" style="display:inline-block;">
+    <span slot="label">Select Example</span>
+    <auro-menu nocheckmark>
+      <auro-menuoption value="flights">
+        <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="terminal" name="plane-diag-fill" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="cars">
+        <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="car-rental-stroke" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="hotels">
+        <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="hotel-filled" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="packages">
+        <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="shop" name="gift-filled" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="cruises">
+        <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="in-flight" name="boarding" customcolor></auro-icon>
+      </auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <auro-select layout="emphasized" shape="pill" size="xl" value="flights" required style="display:inline-block;">
+    <span slot="label">Select Example</span>
+    <span slot="helpText">no displayValue in menuoptions</span>
+    <auro-menu nocheckmark>
+      <auro-menuoption value="flights">
+        <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+      </auro-menuoption>
+      <auro-menuoption value="cars">
+        <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+      </auro-menuoption>
+      <auro-menuoption value="hotels">
+        <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+      </auro-menuoption>
+      <auro-menuoption value="packages">
+        <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+      </auro-menuoption>
+      <auro-menuoption value="cruises">
+        <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+      </auro-menuoption>
+    </auro-menu>
+  </auro-select>
+</div>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+#### Snowflake Layout
+
+The `snowflake` layout is a unique, one off layout that does not follow the normal pattern. There is only one way to use snowflake as shown in the following example.
+
+The `snowflake` layout is only expected to be used on dark backgrounds, in conjunction with `appearance="inverse"`.
+
+<div class="exampleWrapper--ondark">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/snowflake/basic.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/snowflake/basic.html -->
+  <auro-select layout="snowflake" shape="snowflake" appearance="inverse" required style="width:300px;">
+    <span slot="ariaLabel.bib.close">Close Popup</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">Help Text</span>
+    <auro-menu nocheckmark>
+      <auro-menuoption value="flights">
+        <auro-icon category="terminal" name="plane-diag-stroke" customColor></auro-icon> Flights
+      </auro-menuoption>
+      <auro-menuoption value="cars">
+        <auro-icon category="destination" name="car-rental-stroke" customColor></auro-icon> Cars
+      </auro-menuoption>
+      <auro-menuoption value="hotels">
+        <auro-icon category="destination" name="hotel-stroke" customColor></auro-icon> Hotels
+      </auro-menuoption>
+      <auro-menuoption value="packages">
+        <auro-icon category="shop" name="gift-stroke" customColor></auro-icon> Packages
+      </auro-menuoption>
+      <auro-menuoption value="cruises">
+        <auro-icon category="in-flight" name="boarding" customColor></auro-icon> Cruises
+      </auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/snowflake/basic.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/snowflake/basic.html -->
+
+```html
+<auro-select layout="snowflake" shape="snowflake" appearance="inverse" required style="width:300px;">
+  <span slot="ariaLabel.bib.close">Close Popup</span>
+  <span slot="label">Label</span>
+  <span slot="helpText">Help Text</span>
+  <auro-menu nocheckmark>
+    <auro-menuoption value="flights">
+      <auro-icon category="terminal" name="plane-diag-stroke" customColor></auro-icon> Flights
+    </auro-menuoption>
+    <auro-menuoption value="cars">
+      <auro-icon category="destination" name="car-rental-stroke" customColor></auro-icon> Cars
+    </auro-menuoption>
+    <auro-menuoption value="hotels">
+      <auro-icon category="destination" name="hotel-stroke" customColor></auro-icon> Hotels
+    </auro-menuoption>
+    <auro-menuoption value="packages">
+      <auro-icon category="shop" name="gift-stroke" customColor></auro-icon> Packages
+    </auro-menuoption>
+    <auro-menuoption value="cruises">
+      <auro-icon category="in-flight" name="boarding" customColor></auro-icon> Cruises
+    </auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Multi-Select
+
+Sets multi-select mode, allowing multiple options to be selected at once.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/multi-select.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/multi-select.html -->
+  <auro-select multiselect>
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <label slot="placeholder">Select one or more options</label>
+    <span slot="label">multiselect select example</span>
+    <auro-menu>
+      <auro-menuoption value="1">Option 1</auro-menuoption>
+      <auro-menuoption value="2">Option 2</auro-menuoption>
+      <auro-menuoption value="3">Option 3</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/multi-select.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/multi-select.html -->
+
+```html
+<auro-select multiselect>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <label slot="placeholder">Select one or more options</label>
+  <span slot="label">multiselect select example</span>
+  <auro-menu>
+    <auro-menuoption value="1">Option 1</auro-menuoption>
+    <auro-menuoption value="2">Option 2</auro-menuoption>
+    <auro-menuoption value="3">Option 3</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### No Checkmark
+
+Applying the `noCheckmark` attribute will prevent the checkmark icon from being shown on the selected option. The left padding to reserve space for the checkmark will not be shown.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/no-checkmark.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/no-checkmark.html -->
+  <auro-select nocheckmark placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+      <auro-menu>
+          <auro-menuoption value="stops">Stops</auro-menuoption>
+          <auro-menuoption value="price">Price</auro-menuoption>
+          <auro-menuoption value="duration">Duration</auro-menuoption>
+          <auro-menuoption value="departure">Departure</auro-menuoption>
+          <auro-menuoption value="arrival">Arrival</auro-menuoption>
+          <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+      </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/no-checkmark.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/no-checkmark.html -->
+
+```html
+<auro-select nocheckmark placeholder="Placeholder Text">
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Label</span>
+    <auro-menu>
+        <auro-menuoption value="stops">Stops</auro-menuoption>
+        <auro-menuoption value="price">Price</auro-menuoption>
+        <auro-menuoption value="duration">Duration</auro-menuoption>
+        <auro-menuoption value="departure">Departure</auro-menuoption>
+        <auro-menuoption value="arrival">Arrival</auro-menuoption>
+        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Customized Bib Position
+
+The bib position can be customized with `placement`, `offset`, `flip`, `autoPlacement`, and `shift` attributes.
+
+- `placement` specifies the preferred position where the bib should appear relative to the trigger.
+- `offset` sets the distance between the trigger and the bib.
+- When `autoPlacement` is enabled, smart positioning logic is applied to determine the best placement for the bib. If all sides have sufficient space, the bib will appear in the position specified by `placement`.
+- Unless `noFlip` is enabled, if there isn't enough space for the preferred `placement`, the bib will automatically flip to an alternative position.
+- `shift` when enabled, adjusts the bib position when it would overflow the viewport boundaries, ensuring it remains visible.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/floater-config.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/floater-config.html -->
+  <div style="width: 350px">
+    <auro-select offset="20" noFlip placement="bottom-end">
+      <span slot="bib.fullscreen.headline">Bib Headline</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">bottom-end bib with 20px offset and noFlip</span>
+      <auro-menu>
+        <auro-menuoption value="stops">Stops</auro-menuoption>
+        <auro-menuoption value="price">Price</auro-menuoption>
+        <auro-menuoption value="duration">Duration</auro-menuoption>
+        <auro-menuoption value="departure">Departure</auro-menuoption>
+        <auro-menuoption value="arrival">Arrival</auro-menuoption>
+        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+      </auro-menu>
+    </auro-select>
+    <auro-select offset="20" placement="bottom-end">
+      <span slot="bib.fullscreen.headline">Bib Headline</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">bottom-end bib with 20px offset and flip</span>
+      <auro-menu>
+        <auro-menuoption value="stops">Stops</auro-menuoption>
+        <auro-menuoption value="price">Price</auro-menuoption>
+        <auro-menuoption value="duration">Duration</auro-menuoption>
+        <auro-menuoption value="departure">Departure</auro-menuoption>
+        <auro-menuoption value="arrival">Arrival</auro-menuoption>
+        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+      </auro-menu>
+    </auro-select>
+    <auro-select offset="20" noFlip placement="right" autoPlacement noFlip >
+      <span slot="bib.fullscreen.headline">Bib Headline</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">right bib with 20px offset, noFlip and autoPlacement</span>
+      <auro-menu>
+        <auro-menuoption value="stops">Stops</auro-menuoption>
+        <auro-menuoption value="price">Price</auro-menuoption>
+        <auro-menuoption value="duration">Duration</auro-menuoption>
+        <auro-menuoption value="departure">Departure</auro-menuoption>
+        <auro-menuoption value="arrival">Arrival</auro-menuoption>
+        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+      </auro-menu>
+    </auro-select>
+    <auro-select width="350px" offset="20" noFlip placement="bottom-start" shift noFlip >
+      <span slot="bib.fullscreen.headline">Bib Headline</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">bottom-start bib with 20px offset, noFlip and shift</span>
+      <auro-menu>
+        <auro-menuoption value="stops">Stops</auro-menuoption>
+        <auro-menuoption value="price">Price</auro-menuoption>
+        <auro-menuoption value="duration">Duration</auro-menuoption>
+        <auro-menuoption value="departure">Departure</auro-menuoption>
+        <auro-menuoption value="arrival">Arrival</auro-menuoption>
+        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+      </auro-menu>
+    </auro-select>
+  </div>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/floater-config.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/floater-config.html -->
+
+```html
+<div style="width: 350px">
+  <auro-select offset="20" noFlip placement="bottom-end">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">bottom-end bib with 20px offset and noFlip</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <auro-select offset="20" placement="bottom-end">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">bottom-end bib with 20px offset and flip</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <auro-select offset="20" noFlip placement="right" autoPlacement noFlip >
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">right bib with 20px offset, noFlip and autoPlacement</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <auro-select width="350px" offset="20" noFlip placement="bottom-start" shift noFlip >
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">bottom-start bib with 20px offset, noFlip and shift</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+</div>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Placeholder
+
+Use the `placeholder` attribute to inject a custom placeholder option with the select element.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/placeholder.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/placeholder.html -->
+  <auro-select placeholder="Please select your preferred option">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/placeholder.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/placeholder.html -->
+
+```html
+<auro-select placeholder="Please select your preferred option">
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Label</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Required
+
+When present, the `required` attribute specifies that a select field must be filled out before submitting the form.
+
+When the validity check fails the validityState, equals `valueMissing`. The error message for the `valueMissing` validityState can be set to a custom string using the `setCustomValidityValueMissing`. There is no default error message defined.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/required.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/required.html -->
+  <auro-select required setCustomValidityValueMissing="Custom required validation error message." placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/required.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/required.html -->
+
+```html
+<auro-select required setCustomValidityValueMissing="Custom required validation error message." placeholder="Placeholder Text">
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Label</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Value
+
+Use the `value` property to define a preset value on the `auro-select` element. The `value` of `auro-select` must match the `value` defined of a single `auro-menuoption`. Upon initially rendering the component, if the `value` does not match an `auro-menuoption`, the `value` of `auro-select` will be set to `undefined`.
+
+To pre-set the value of auro-select on load, use the `value` property. The `selected` attribute on auro-menuoption is designed to illustrate state in the DOM.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/value.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/value.html -->
+  <auro-button id="validValueExampleBtn">Set Value to Valid Option</auro-button>
+  <auro-button id="invalidValueExampleBtn">Set Value to Invalid Option</auro-button>
+  <br/><br/>
+  <auro-select id="valueExample" multiselect value='["price", "duration"]'>
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Name</span>
+    <auro-menu>
+      <auro-menuoption id="option-0" value="stops">Stops</auro-menuoption>
+      <auro-menuoption id="option-1" value="price">Price</auro-menuoption>
+      <auro-menuoption id="option-2" value="duration">Duration</auro-menuoption>
+      <auro-menuoption id="option-3" value="departure">Departure</auro-menuoption>
+      <auro-menuoption id="option-4" value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption id="option-5" value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/value.html -->
+
+```html
+<auro-button id="validValueExampleBtn">Set Value to Valid Option</auro-button>
+<auro-button id="invalidValueExampleBtn">Set Value to Invalid Option</auro-button>
+<br/><br/>
+<auro-select id="valueExample" multiselect value='["price", "duration"]'>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Name</span>
+  <auro-menu>
+    <auro-menuoption id="option-0" value="stops">Stops</auro-menuoption>
+    <auro-menuoption id="option-1" value="price">Price</auro-menuoption>
+    <auro-menuoption id="option-2" value="duration">Duration</auro-menuoption>
+    <auro-menuoption id="option-3" value="departure">Departure</auro-menuoption>
+    <auro-menuoption id="option-4" value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption id="option-5" value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/value.js -->
+
+```js
+export function valueExample() {
+  const valueExample = document.querySelector('#valueExample');
+
+  document.querySelector('#validValueExampleBtn').addEventListener('click', () => {
+    valueExample.value = '["arrival", "prefer alaska"]';
+  });
+
+  document.querySelector('#invalidValueExampleBtn').addEventListener('click', () => {
+    valueExample.value = '["flight course"]';
+  });
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## Method Examples
+
+### Reset State
+
+Use the `reset()` method to reset the `<auro-select>`'s `value` and `validity` state. Doing so will preserve all other attributes and properties.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/reset-state.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/reset-state.html -->
+  <auro-button id="resetStateBtn">Reset</auro-button>
+  <br/><br/>
+  <auro-select id="resetStateExample" value="price" placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <span slot="label">Name</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reset-state.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/reset-state.html -->
+
+```html
+<auro-button id="resetStateBtn">Reset</auro-button>
+<br/><br/>
+<auro-select id="resetStateExample" value="price" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Please select a preference</span>
+  <span slot="label">Label</span>
+  <span slot="label">Name</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -776,14 +1357,105 @@ Use the `label` slot to give your users contextual information about their selec
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reset-state.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/reset-state.js -->
+
+```js
+export function resetStateExample() {
+  const elem = document.querySelector('#resetStateExample');
+
+  document.querySelector('#resetStateBtn').addEventListener('click', () => {
+    elem.reset();
+  });
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## Slot Examples
+
+### Custom Value Display
+
+The `auro-select` supports the new formkit feature set enabling customized content displayed when a value is selected.
+
+e.g. You may have a menu option that reads "SeaTac International Airport". However, when that option is selected, you would like the value displayed in the auro-select to just be the airport code "SEA".
+
+The custom display value content is inserted using `slot="displayValue"` on each menu option. The `auro-select` component does not style or restrict the slotted content. It is the responsibility of the implementor to insure the content fits within the auro-select container and is styled appropriately.
+
+The following example demonstrates menu options with an icon and text. When selected, the auro-select renders an icon with no text.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/emphasized/constant-display-value.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/emphasized/constant-display-value.html -->
+  <auro-select layout="emphasized" shape="pill" size="xl" value="flights" forceDisplayValue style="display:inline-block;">
+    <span slot="label">Select Example</span>
+    <auro-menu nocheckmark>
+      <auro-menuoption value="flights">
+        <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="terminal" name="plane-diag-fill" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="cars">
+        <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="car-rental-stroke" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="hotels">
+        <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="hotel-filled" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="packages">
+        <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="shop" name="gift-filled" customcolor></auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="cruises">
+        <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+        <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="in-flight" name="boarding" customcolor></auro-icon>
+      </auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/emphasized/constant-display-value.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/emphasized/constant-display-value.html -->
+
+```html
+<auro-select layout="emphasized" shape="pill" size="xl" value="flights" forceDisplayValue style="display:inline-block;">
+  <span slot="label">Select Example</span>
+  <auro-menu nocheckmark>
+    <auro-menuoption value="flights">
+      <auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
+      <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="terminal" name="plane-diag-fill" customcolor></auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="cars">
+      <auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
+      <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="car-rental-stroke" customcolor></auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="hotels">
+      <auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
+      <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="destination" name="hotel-filled" customcolor></auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="packages">
+      <auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
+      <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="shop" name="gift-filled" customcolor></auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="cruises">
+      <auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
+      <auro-icon style="--ds-auro-icon-size: 40px;" slot="displayValue" category="in-flight" name="boarding" customcolor></auro-icon>
+    </auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### helpText <a name="helpText"></a>
+### Help Text
+
 Use the `helpText` slot to provide additional information back to your user about their selection option(s).
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/helpText.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/helpText.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/help-text.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/help-text.html -->
   <auro-select placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
@@ -801,8 +1473,8 @@ Use the `helpText` slot to provide additional information back to your user abou
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/helpText.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/helpText.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/help-text.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/help-text.html -->
 
 ```html
 <auro-select placeholder="Placeholder Text">
@@ -822,68 +1494,301 @@ Use the `helpText` slot to provide additional information back to your user abou
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-## Functional Examples
-
-### Reset State
+### Label
+
+Use the `label` slot to give your users contextual information about their selection options. This `label` content is also helpful for assistive devices.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/label.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/label.html -->
+  <auro-select>
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Please select a preference</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/label.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/label.html -->
+
+```html
+<auro-select>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Please select a preference</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Optional Label
+
+The `<auro-select>` supports an `optionalLabel` slot, where users can can override the default `(optional)` notification text.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/optional-label.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/optional-label.html -->
+  <auro-select>
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Please select a preference</span>
+    <span slot="optionalLabel" style="color: grey; font-size: small"> - optional</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/optional-label.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/optional-label.html -->
+
+```html
+<auro-select>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Please select a preference</span>
+  <span slot="optionalLabel" style="color: grey; font-size: small"> - optional</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## CSS Shadow Part Examples
+
+### Custom Bib Height
+
+This example shows how to set a custom height for the bib from `<auro-dropdown>`.
+
+Custom height dimensions are set by using the `dropdownSize` CSS Part and then applying a `max-height` rule and value.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/custom-bib-height.html) -->
+  <!-- The below content is automatically added from ../apiExamples/custom-bib-height.html -->
+  <auro-select id="customBibHeightExample" placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <style>
+    #customBibHeightExample::part(dropdownSize) {
+      max-height: 100px;
+    }
+  </style>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/custom-bib-height.html) -->
+<!-- The below code snippet is automatically added from ../apiExamples/custom-bib-height.html -->
+
+```html
+<auro-select id="customBibHeightExample" placeholder="Placeholder Text">
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Label</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+<style>
+  #customBibHeightExample::part(dropdownSize) {
+    max-height: 100px;
+  }
+</style>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## Common Usage Patterns & Functional Examples
+
+### Icons in Options
+
+Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/with-icons.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/with-icons.html -->
+  <auro-select placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <auro-menu>
+      <auro-menuoption value="air">
+        <auro-icon label customColor category="health" name="air">Air</auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="covidtest">
+        <auro-icon label customColor category="health" name="covid-test">Covid Test</auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="health">
+        <auro-icon label customColor category="health" name="health">Health</auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="mask">
+        <auro-icon label customColor category="health" name="mask">Mask</auro-icon>
+      </auro-menuoption>
+      <auro-menuoption value="spraybottle">
+        <auro-icon label customColor category="health" name="spraybottle">Spray Bottle</auro-icon>
+      </auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/with-icons.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/with-icons.html -->
+
+```html
+<auro-select placeholder="Placeholder Text">
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Label</span>
+  <auro-menu>
+    <auro-menuoption value="air">
+      <auro-icon label customColor category="health" name="air">Air</auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="covidtest">
+      <auro-icon label customColor category="health" name="covid-test">Covid Test</auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="health">
+      <auro-icon label customColor category="health" name="health">Health</auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="mask">
+      <auro-icon label customColor category="health" name="mask">Mask</auro-icon>
+    </auro-menuoption>
+    <auro-menuoption value="spraybottle">
+      <auro-icon label customColor category="health" name="spraybottle">Spray Bottle</auro-icon>
+    </auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Nested Submenus
 
-Use the `reset()` method to reset the `<auro-select>`'s `value` and `validity` state. Doing so will preserve all other attributes and properties.
+This example shows nesting `<auro-menu>` elements to create submenus.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/resetState.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/resetState.html -->
-  <auro-button id="resetStateBtn">Reset</auro-button>
-  <br/><br/>
-  <auro-select id="resetStateExample" value="price" placeholder="Placeholder Text">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/with-submenus.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/with-submenus.html -->
+  <auro-select placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
-    <span slot="label">Name</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
       <auro-menuoption value="duration">Duration</auro-menuoption>
+      <hr>
+      <auro-menu>
+        <auro-menuoption value="apples">Apples</auro-menuoption>
+        <auro-menuoption value="oranges">Oranges</auro-menuoption>
+        <auro-menuoption value="pears">Pears</auro-menuoption>
+        <auro-menuoption value="grapes">Grapes</auro-menuoption>
+        <auro-menuoption value="kiwi">Kiwi</auro-menuoption>
+        <hr>
+        <auro-menu>
+          <auro-menuoption value="person">Person</auro-menuoption>
+          <auro-menuoption value="woman">Woman</auro-menuoption>
+          <auro-menuoption value="man">Man</auro-menuoption>
+          <auro-menuoption value="camera">Camera</auro-menuoption>
+          <auro-menuoption value="tv">TV</auro-menuoption>
+        </auro-menu>
+      </auro-menu>
+      <hr>
       <auro-menuoption value="departure">Departure</auro-menuoption>
       <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+      <hr>
+      <auro-menu>
+        <auro-menuoption value="cars">Cars</auro-menuoption>
+        <auro-menuoption value="trucks">Trucks</auro-menuoption>
+        <auro-menuoption value="boats">Boats</auro-menuoption>
+        <auro-menuoption value="planes">Planes</auro-menuoption>
+        <auro-menuoption value="motorcycles">Motorcycles</auro-menuoption>
     </auro-menu>
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/resetState.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/resetState.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/with-submenus.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/with-submenus.html -->
 
 ```html
-<auro-button id="resetStateBtn">Reset</auro-button>
-<br/><br/>
-<auro-select id="resetStateExample" value="price" placeholder="Placeholder Text">
+<auro-select placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
   <span slot="label">Label</span>
-  <span slot="label">Name</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
     <auro-menuoption value="duration">Duration</auro-menuoption>
+    <hr>
+    <auro-menu>
+      <auro-menuoption value="apples">Apples</auro-menuoption>
+      <auro-menuoption value="oranges">Oranges</auro-menuoption>
+      <auro-menuoption value="pears">Pears</auro-menuoption>
+      <auro-menuoption value="grapes">Grapes</auro-menuoption>
+      <auro-menuoption value="kiwi">Kiwi</auro-menuoption>
+      <hr>
+      <auro-menu>
+        <auro-menuoption value="person">Person</auro-menuoption>
+        <auro-menuoption value="woman">Woman</auro-menuoption>
+        <auro-menuoption value="man">Man</auro-menuoption>
+        <auro-menuoption value="camera">Camera</auro-menuoption>
+        <auro-menuoption value="tv">TV</auro-menuoption>
+      </auro-menu>
+    </auro-menu>
+    <hr>
     <auro-menuoption value="departure">Departure</auro-menuoption>
     <auro-menuoption value="arrival">Arrival</auro-menuoption>
-    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    <hr>
+    <auro-menu>
+      <auro-menuoption value="cars">Cars</auro-menuoption>
+      <auro-menuoption value="trucks">Trucks</auro-menuoption>
+      <auro-menuoption value="boats">Boats</auro-menuoption>
+      <auro-menuoption value="planes">Planes</auro-menuoption>
+      <auro-menuoption value="motorcycles">Motorcycles</auro-menuoption>
   </auro-menu>
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/resetState.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/resetState.js -->
-
-```js
-export function resetStateExample() {
-  const elem = document.querySelector('#resetStateExample');
-
-  document.querySelector('#resetStateBtn').addEventListener('click', () => {
-    elem.reset();
-  });
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
 ### Extract value
@@ -891,8 +1796,8 @@ export function resetStateExample() {
 The following example illustrates how a user may query the `element.value` or `element.optionSelected` for the current value or complete option object that is selected.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueExtraction.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/valueExtraction.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/value-extraction.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/value-extraction.html -->
   <auro-select id="valueExtraction" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
@@ -910,8 +1815,8 @@ The following example illustrates how a user may query the `element.value` or `e
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueExtraction.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueExtraction.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value-extraction.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/value-extraction.html -->
 
 ```html
 <auro-select id="valueExtraction" placeholder="Placeholder Text">
@@ -929,8 +1834,8 @@ The following example illustrates how a user may query the `element.value` or `e
 <auro-button id="valueExtractionBtn">Get current value</auro-button>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueExtraction.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueExtraction.js -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value-extraction.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/value-extraction.js -->
 
 ```js
 export function valueExtractionExample() {
@@ -953,8 +1858,8 @@ export function valueExtractionExample() {
 This example programmatically adds the `error` state when a user selects an option that is greater than `2`.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/customErrorValidity.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/customErrorValidity.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/custom-error-validity.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/custom-error-validity.html -->
   <auro-select id="primaryError" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
@@ -971,8 +1876,8 @@ This example programmatically adds the `error` state when a user selects an opti
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/customErrorValidity.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/customErrorValidity.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/custom-error-validity.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/custom-error-validity.html -->
 
 ```html
 <auro-select id="primaryError" placeholder="Placeholder Text">
@@ -989,8 +1894,8 @@ This example programmatically adds the `error` state when a user selects an opti
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/customErrorValidity.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/customErrorValidity.js -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/custom-error-validity.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/custom-error-validity.js -->
 
 ```js
 export function customErrorValidityExample(elem) {
@@ -1008,279 +1913,18 @@ export function customErrorValidityExample(elem) {
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Loading<a name="loading"></a>
-While content is loading, the menu can either remain empty or display a loading placeholder
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/loading.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/loading.html -->
-  <auro-select id="loadingExample">
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Please select a preference</span>
-    <auro-menu id="loadingExampleSelectMenu">
-      <auro-loader slot="loadingIcon" orbit xs></auro-loader><span slot="loadingText">Loading...</span>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/loading.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/loading.js -->
-
-```js
-export function auroMenuLoadingExample() {
-  const select = document.querySelector("#loadingExample");
-  const menu = document.querySelector("#loadingExampleSelectMenu");
-
-  const emptyMenu = () => {
-    const menuoptions = menu.querySelectorAll('auro-menuoption');
-    menuoptions.forEach(mo => menu.removeChild(mo));
-  }
-
-  const fillMenu = () => {
-      menu.innerHTML += `
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>`;
-  }
-
-  select.addEventListener("click", () => {
-    if (!menu.hasAttribute('loading') && !select.value) {
-      emptyMenu();
-      menu.setAttribute('loading', 'loading');
-      setTimeout(() => {
-        menu.removeAttribute('loading');
-        fillMenu();
-      }, 1000);
-    }
-  });
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/loading.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/loading.html -->
-
-```html
-<auro-select id="loadingExample">
-  <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">Please select a preference</span>
-  <auro-menu id="loadingExampleSelectMenu">
-    <auro-loader slot="loadingIcon" orbit xs></auro-loader><span slot="loadingText">Loading...</span>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-### displayValue <a name="displayValue"></a>
-The label for selected option can be customized using `displayValue` slot under `<menuoption>.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/displayValue.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/displayValue.html -->
-  <auro-select id="displayValueExample" autocomplete="address-level1">
-    <span slot="bib.fullscreen.headline">Select Your Gender</span>
-    <span slot="label">Gender</span>
-    <span slot="displayValue"></span>
-      <auro-menu>
-        <auro-menuoption value="m" data-display="Male">M - Male
-          <span slot="displayValue">Male</span>
-        </auro-menuoption>
-        <auro-menuoption value="f" data-display="Female">F - Female
-          <span slot="displayValue">Female</span>
-        </auro-menuoption>
-        <auro-menuoption value="x" data-display="Unspecified">X - Unspecified
-          <span slot="displayValue">Unspecified</span>
-        </auro-menuoption>
-        <auro-menuoption value="u" data-display="Undisclosed">U - Undisclosed
-          <span slot="displayValue">Undisclosed</span>
-        </auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/displayValue.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/displayValue.html -->
-
-```html
-<auro-select id="displayValueExample" autocomplete="address-level1">
-  <span slot="bib.fullscreen.headline">Select Your Gender</span>
-  <span slot="label">Gender</span>
-  <span slot="displayValue"></span>
-    <auro-menu>
-      <auro-menuoption value="m" data-display="Male">M - Male
-        <span slot="displayValue">Male</span>
-      </auro-menuoption>
-      <auro-menuoption value="f" data-display="Female">F - Female
-        <span slot="displayValue">Female</span>
-      </auro-menuoption>
-      <auro-menuoption value="x" data-display="Unspecified">X - Unspecified
-        <span slot="displayValue">Unspecified</span>
-      </auro-menuoption>
-      <auro-menuoption value="u" data-display="Undisclosed">U - Undisclosed
-        <span slot="displayValue">Undisclosed</span>
-      </auro-menuoption>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-### Customized bib position
-The bib position can be customized with `placement`, `offset`, `flip`, `autoPlacement`, and `shift` attributes.
+### Max Height on Menu
 
-- `placement` specifies the preferred position where the bib should appear relative to the trigger.
-- `offset` sets the distance between the trigger and the bib.
-- When `autoPlacement` is enabled, smart positioning logic is applied to determine the best placement for the bib. If all sides have sufficient space, the bib will appear in the position specified by `placement`.
-- Unless `noFlip` is enabled, if there isn't enough space for the preferred `placement`, the bib will automatically flip to an alternative position.
-- `shift` when enabled, adjusts the bib position when it would overflow the viewport boundaries, ensuring it remains visible.
+Setting a max height on the menu will cause the bib to become scrollable when the content exceeds the max height.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/floaterConfig.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/floaterConfig.html -->
-  <div style="width: 350px">
-    <auro-select offset="20" noFlip placement="bottom-end">
-      <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">Label</span>
-      <span slot="helpText">bottom-end bib with 20px offset and noFlip</span>
-      <auro-menu>
-        <auro-menuoption value="stops">Stops</auro-menuoption>
-        <auro-menuoption value="price">Price</auro-menuoption>
-        <auro-menuoption value="duration">Duration</auro-menuoption>
-        <auro-menuoption value="departure">Departure</auro-menuoption>
-        <auro-menuoption value="arrival">Arrival</auro-menuoption>
-        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-      </auro-menu>
-    </auro-select>
-    <auro-select offset="20" placement="bottom-end">
-      <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">Label</span>
-      <span slot="helpText">bottom-end bib with 20px offset and flip</span>
-      <auro-menu>
-        <auro-menuoption value="stops">Stops</auro-menuoption>
-        <auro-menuoption value="price">Price</auro-menuoption>
-        <auro-menuoption value="duration">Duration</auro-menuoption>
-        <auro-menuoption value="departure">Departure</auro-menuoption>
-        <auro-menuoption value="arrival">Arrival</auro-menuoption>
-        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-      </auro-menu>
-    </auro-select>
-    <auro-select offset="20" noFlip placement="right" autoPlacement noFlip >
-      <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">Label</span>
-      <span slot="helpText">right bib with 20px offset, noFlip and autoPlacement</span>
-      <auro-menu>
-        <auro-menuoption value="stops">Stops</auro-menuoption>
-        <auro-menuoption value="price">Price</auro-menuoption>
-        <auro-menuoption value="duration">Duration</auro-menuoption>
-        <auro-menuoption value="departure">Departure</auro-menuoption>
-        <auro-menuoption value="arrival">Arrival</auro-menuoption>
-        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-      </auro-menu>
-    </auro-select>
-    <auro-select width="350px" offset="20" noFlip placement="bottom-start" shift noFlip >
-      <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">Label</span>
-      <span slot="helpText">bottom-start bib with 20px offset, noFlip and shift</span>
-      <auro-menu>
-        <auro-menuoption value="stops">Stops</auro-menuoption>
-        <auro-menuoption value="price">Price</auro-menuoption>
-        <auro-menuoption value="duration">Duration</auro-menuoption>
-        <auro-menuoption value="departure">Departure</auro-menuoption>
-        <auro-menuoption value="arrival">Arrival</auro-menuoption>
-        <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-      </auro-menu>
-    </auro-select>
-  </div>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/floaterConfig.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/floaterConfig.html -->
-
-```html
-<div style="width: 350px">
-  <auro-select offset="20" noFlip placement="bottom-end">
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Label</span>
-    <span slot="helpText">bottom-end bib with 20px offset and noFlip</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <auro-select offset="20" placement="bottom-end">
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Label</span>
-    <span slot="helpText">bottom-end bib with 20px offset and flip</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <auro-select offset="20" noFlip placement="right" autoPlacement noFlip >
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Label</span>
-    <span slot="helpText">right bib with 20px offset, noFlip and autoPlacement</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <auro-select width="350px" offset="20" noFlip placement="bottom-start" shift noFlip >
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/max-height.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/max-height.html -->
+  <auro-select>
+    <span slot="ariaLabel.bib.close">Close Popup</span>
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">Label</span>
-    <span slot="helpText">bottom-start bib with 20px offset, noFlip and shift</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-</div>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-### Dropdown with fullscreen bib
-
-You can make the dropdown open in fullscreen at a specific breakpoint by setting `fullscreenBreakpoint`.
-
-The default value of `fullscreenBreakpoint` is `sm`. 
-
-Breakpoint token can be found [here](https://auro.alaskaair.com/getting-started/developers/design-tokens)
-
-To support fullcreen bib, setting `bib.fullscreen.headline` is **STRONGLY RECOMMENDED**.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/fullscreenBreakpoint.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/fullscreenBreakpoint.html -->
-  <auro-select fullscreenBreakpoint="lg">
     <span slot="label">Select Example</span>
-    <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <auro-menu>
+    <auro-menu style="max-height: 150px;">
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
       <auro-menuoption value="duration">Duration</auro-menuoption>
@@ -1293,14 +1937,15 @@ To support fullcreen bib, setting `bib.fullscreen.headline` is **STRONGLY RECOMM
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/fullscreenBreakpoint.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/fullscreenBreakpoint.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/max-height.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/max-height.html -->
 
 ```html
-<auro-select fullscreenBreakpoint="lg">
-  <span slot="label">Select Example</span>
+<auro-select>
+  <span slot="ariaLabel.bib.close">Close Popup</span>
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <auro-menu>
+  <span slot="label">Select Example</span>
+  <auro-menu style="max-height: 150px;">
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
     <auro-menuoption value="duration">Duration</auro-menuoption>
@@ -1313,13 +1958,13 @@ To support fullcreen bib, setting `bib.fullscreen.headline` is **STRONGLY RECOMM
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### in Dialog
+### Select in Dialog
 
 The component can be in a dialog.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inDialog.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/inDialog.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/in-dialog.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/in-dialog.html -->
   <div>
     <auro-button id="select-dialog-opener">Select in Dialog</auro-button>
     <auro-dialog id="select-dialog">
@@ -1344,8 +1989,8 @@ The component can be in a dialog.
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/inDialog.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/inDialog.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/in-dialog.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/in-dialog.html -->
 
 ```html
 <div>
@@ -1370,8 +2015,8 @@ The component can be in a dialog.
 </div>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/inDialog.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/inDialog.js -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/in-dialog.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/in-dialog.js -->
 
 ```js
 export function inDialogExample() {
@@ -1384,13 +2029,13 @@ export function inDialogExample() {
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### Watch for value changes
+### Watch for Value Changes
 
 The following example listens for the `auroMenu-selectedOption` event. Once triggered, element.value or element.optionSelected may be queried for the new value or complete option object.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueAlert.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/valueAlert.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/value-alert.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/value-alert.html -->
   <auro-select id="valueAlert" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Label</span>
@@ -1407,8 +2052,8 @@ The following example listens for the `auroMenu-selectedOption` event. Once trig
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueAlert.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueAlert.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value-alert.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/value-alert.html -->
 
 ```html
 <auro-select id="valueAlert" placeholder="Placeholder Text">
@@ -1425,8 +2070,8 @@ The following example listens for the `auroMenu-selectedOption` event. Once trig
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueAlert.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueAlert.js -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/value-alert.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/value-alert.js -->
 
 ```js
 export function valueAlertExample() {
@@ -1440,4 +2085,39 @@ export function valueAlertExample() {
 }
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
+</auro-accordion>
+
+## Restyle Component with CSS Variables
+
+The component may be restyled by changing the values of the following token(s).
+
+<!-- Remove section if component does not have any component specific tokens -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../src/styles/tokens.scss) -->
+<!-- The below code snippet is automatically added from ./../src/styles/tokens.scss -->
+
+```scss
+@use "@aurodesignsystem/design-tokens/dist/themes/alaska/SCSSVariables--alaska" as v;
+
+:host(:not([ondark])),
+:host(:not([appearance='inverse'])) {
+  --ds-auro-select-border-color: var(--ds-basic-color-border-bold, #{v.$ds-basic-color-border-bold});
+  --ds-auro-select-background-color: var(--ds-basic-color-surface-default, #{v.$ds-basic-color-surface-default});
+  --ds-auro-select-label-text-color: var(--ds-basic-color-texticon-muted, #{v.$ds-basic-color-texticon-muted});
+  --ds-auro-select-placeholder-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
+  --ds-auro-select-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
+  --ds-auro-select-error-icon-color: var(--ds-basic-color-status-error, #{v.$ds-basic-color-status-error});
+  --ds-auro-select-outline-color: transparent;
+}
+
+:host([ondark]),
+:host([appearance='inverse']) {
+  --ds-auro-select-border-color: var(--ds-basic-color-border-inverse, #{v.$ds-basic-color-border-inverse});
+  --ds-auro-select-background-color: var(--ds-advanced-color-shared-background-inverse, #{v.$ds-advanced-color-shared-background-inverse});
+  --ds-auro-select-label-text-color: var(--ds-basic-color-texticon-inverse-muted, #{v.$ds-basic-color-texticon-inverse-muted});
+  --ds-auro-select-placeholder-text-color: var(--ds-basic-color-texticon-inverse, #{v.$ds-basic-color-texticon-inverse});
+  --ds-auro-select-text-color: var(--ds-basic-color-texticon-inverse, #{v.$ds-basic-color-texticon-inverse});
+  --ds-auro-select-error-icon-color: var(--ds-advanced-color-state-error-inverse, #{v.$ds-advanced-color-state-error-inverse});
+  --ds-auro-select-outline-color: transparent;
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->