+```html preview 230px
+
@@ -376,135 +248,58 @@ Use `--select-height` to set the max-height of the dropdown.
-```
-### Width
-
-By default, the select width is `fit-content` and the same goes for the listbox containing the options.
-
-You can specify width on the `vwc-select` if required (the listbox will not be affected by this setting).
-
-```html preview 230px
-
-
-
-
-
```
-## Properties
+## API Reference
+
+### Properties
-| Name | Type | Default | Description |
-| ----------------- | ---------- | ----------- | ---------------------------------------------------------------- |
-| `options` | `Option[]` | `[]` | A read-only list of options. |
-| `selectedOptions` | `Option[]` | `[]` | A read-only collection of the selected options. |
-| `selectedIndex` | `number` | `undefined` | The index of the selected option or -1 if no option is selected. |
+| Name | Type | Description |
+| ------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **appearance** | `fieldset` (default), `ghost` | Sets the element's appearance |
+| **disabled** | `boolean` | Sets the element's disabled state. A disabled element will not be included during form submission. |
+| **error-text** | `string` | Sets the element's error text |
+| **fixed-dropdown** | `boolean` | Sets the position strategy of the dropdown to fixed |
+| **helper-text** | `string` | Sets the element's helper text |
+| **icon** | _Enum_:
`[icon-name]` | A decorative icon for the element. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s |
+| **label** | `string` | Sets the element's label |
+| **multiple** | `boolean` | Sets the element to allow multiple selections |
+| **open** | `boolean` | Sets the element's menu to be open |
+| **placeholder** | `string` | Sets the text to be displayed when no option is selected |
+| **scale** | `normal` (default), `condensed` | Sets the display size of the input element |
+| **shape** | `rounded` (default), `pill` | Sets the shape of the select element |
+| **success-text** | `string` | Sets the element's success text |
-## Events
+### Events
-| Name | Type | Bubbles | Composed | Description |
-| -------- | -------------------------- | ------- | -------- | ----------------------------- |
-| `input` | `CustomEvent` | Yes | Yes | Fired when the menu is opened |
-| `change` | `CustomEvent` | Yes | No | Fired when the menu is closed |
+| Name | Type | Bubbles | Composed | Description |
+| ---------- | ------------------------ | ------- | -------- | ----------------------------------------------- |
+| **input** | `CustomEvent` | No | Yes | Fired when an option is selected or unselected. |
+| **change** | `CustomEvent` | No | Yes | Fired when an option is selected or unselected. |
-## Caveat
-
-Document elements display precedence is formed by the imaginary z-axis [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context), commonly by order of which elements are rendered and special properties (e.g. _z-index_).
-Select component is a low level element, unaware of its document context, but is, in most cases, required to overlay on top of all elements.
-If needed a `z-index` value can be set on the host
-
-## Accessibility
-
-### Aria Label
-
-A select requires a label to be set for screen readers to be able to describe the component.
-If label is set, it is used as the `aria-label` attribute value on the host element.
-If label is not set, please make sure to add an `aria-label` attribute to the host element.
+### Slots
-## Use Cases
-
-### Country Code
-
-```html preview 250px
-
-
-
-
-
-
-
-```
-
-### Call Status
-
-```html preview 250px
-
-
-
- 00:00:00
-
-
-
-
-
-
-
-
-
-
-
-
-
-```
+
diff --git a/libs/components/src/lib/select/USE-CASES.md b/libs/components/src/lib/select/USE-CASES.md
new file mode 100644
index 0000000000..29c04cfa28
--- /dev/null
+++ b/libs/components/src/lib/select/USE-CASES.md
@@ -0,0 +1,169 @@
+## Validation
+
+### In a Form
+
+When a Select is placed inside a `form` element and validation logic is set on the Select component, the Select is validated when the `form` is submitted (as per a native `select` element).
+
+Below, the "Title" field Select is marked as required and is validated when the `form` is submitted.
+
+```html preview 360px
+
+
+
+```
+
+### Single Field
+
+The Select component can be validated like the native `select` element.
+
+Below, the Select is `required` but it has no selected option. The `checkedValidity()` method is called on the Select to validate it.
+
+```html preview
+
+
+
+
+
+
+
+
+```
+
+## International Phone Number
+
+The Select component is used in the example below as the dialing code part of an international phone number input field.
+
+```html preview 240px
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Call Status
+
+```html preview 250px
+
+
+ 00:00:00
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/libs/components/src/lib/select/VARIATIONS.md b/libs/components/src/lib/select/VARIATIONS.md
new file mode 100644
index 0000000000..b02f5f6883
--- /dev/null
+++ b/libs/components/src/lib/select/VARIATIONS.md
@@ -0,0 +1,340 @@
+## Labelling
+
+### Label Text
+
+The `label` attribute provides a short description of the purpose of the Select.
+
+```html preview 270px
+
+
+
+
+
+
+```
+
+
+ If you can not use the visible label, provide it using the aria-label attribute.
+ It will be announced by screen readers so that those users will know the purpose of the Select.
+
+
+### Helper Text
+
+The `helper-text` attribute provides additional information about the purpose of the Select.
+
+To add HTML to the helper text, use the [helper-text slot](/components/select/code/#helper-text-slot).
+
+```html preview 320px
+
+
+
+
+
+
+
+
+
+```
+
+### Placeholder Text
+
+The `placeholder` attribute provides some text to be displayed when no option has been selected.
+
+```html preview 270px
+
+
+
+
+
+
+```
+
+
+ Using placeholder text to label the Select harms accessibility and user experience. The label text is visually and programmatically associated with its corresponding form control.
+
+
+## Selected Option
+
+To provide a selected option, use the `selected` attribute on the selected [Option](/components/option/#selected).
+
+```html preview 270px
+
+
+
+
+
+
+```
+
+### Selected Option Label
+
+Use the `label` attribute on the [Option](/components/option/#label) component to proviode a different label to be displayed when the option is selected.
+
+In the example below, the state code is displayed when selected but the full state name is displayed in the option list.
+
+```html preview 320px
+
+
+
+
+
+
+
+
+
+```
+
+## Validation Feedback
+
+### Error Text
+
+The `error-text` attribute provides a custom error message. Any current error state will be overridden by `error-text`.
+
+```html preview 270px
+
+
+
+
+
+
+
+
+```
+
+### Success Text
+
+The `success-text` attribute provides a custom success message. Any current error state will be overridden by `success-text`.
+
+```html preview 270px
+
+
+
+
+
+
+
+
+```
+
+## Icon
+
+The `icon` attribute displays an icon from the [icon library](/icons/icons-gallery), which prefixes the Select element.
+
+To add custom icons, use the `icon` [slot](/components/select/code/#icon-slot) provided.
+
+```html preview 270px
+
+
+
+
+
+
+
+
+
+
+```
+
+## Scale
+
+The `scale` attribute controls the select element display size.
+Use `condensed` in situations when space is limited, for example, inside a Data Grid cell.
+
+```html preview 270px
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+
+ The reason for using scale for form elements and not size (as used in other components such as Button), is that size is a HTML attribute that can be used on input elements (and also Text Field) to control the width of the input.
+
+
+## Shape
+
+The `shape` attribute controls the border radius of the Select input element.
+
+```html preview 270px
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Appearance
+
+The `appearance` attribute controls the style of the select element.
+Use `ghost` in combination with a containing element which provides a border, for example when used inside the [leading action items slot of Text Field](/components/text-field/code/#leading-action-items-slot).
+
+```html preview 270px
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Multiple
+
+The `multiple` attribute allows the user to select more than one option. When in the multiple selection state, the options will always be visible.
+
+For a better user experience, consider using a [Checkbox](/components/checkbox/) list or the [Searchable Select](/components/searchable-select/) if there are many options to pick from.
+
+```html preview 230px
+
+
+
+
+
+
+
+
+```
+
+## Disabled
+
+The `disabled` attribute disables the select element.
+
+```html preview 270px
+
+
+
+
+
+
+```
diff --git a/libs/components/src/lib/select/ui.test.ts b/libs/components/src/lib/select/ui.test.ts
index 69b1b5277d..3e692d81a7 100644
--- a/libs/components/src/lib/select/ui.test.ts
+++ b/libs/components/src/lib/select/ui.test.ts
@@ -1,8 +1,6 @@
-import * as path from 'path';
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import {
- extractHTMLBlocksFromReadme,
loadComponents,
loadTemplate,
} from '../../visual-tests/visual-tests-utils.js';
@@ -67,8 +65,7 @@ async function testScaleOptions({ page }: { page: Page }) {
}
test('should show the component', async ({ page }: { page: Page }) => {
- const template =
- `
+ const template = `
` +
- extractHTMLBlocksFromReadme(
- path.join(new URL('.', import.meta.url).pathname, 'README.md')
- ).reduce(
- (htmlString: string, block: string) =>
- `${htmlString} ${block}
`,
- ''
- );
+ #wrapper > div {
+ margin: 5px;
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 00:00:00
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 00:00:00
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ `;
await page.setViewportSize({ width: 2300, height: 720 });
diff --git a/libs/components/src/lib/text-field/README.md b/libs/components/src/lib/text-field/README.md
index f320f947d1..27f24b57ee 100644
--- a/libs/components/src/lib/text-field/README.md
+++ b/libs/components/src/lib/text-field/README.md
@@ -180,12 +180,13 @@ The `helper-text` slot allows you to use rich content as the text-field's helper
| Name | Type | Description |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `appearance` | `fieldset`, `ghost` | Sets the input element's appearance |
+| `appearance` | `fieldset` (default), `ghost` | Sets the input element's appearance |
| `autocomplete` | `off`, `on`, `` | Hint for form autofill feature |
| `autofocus` | `boolean` | Indicates that an element should be focused on page load, or when the Dialog that it is part of is displayed |
| `char-count` | `boolean` | Use in combination with `maxlength` to display a character count |
| `disabled` | `boolean` | Whether the input element is disabled |
| `inputmode` | enum: `none`, `text`, `decimal` `numeric`, `tel`, `search`, `email`, `url` | Allows a browser to display an appropriate virtual keyboard |
+| `label` | `string` | Label of the Text Field |
| `list` | `string` | Value of the id attribute of the `