<!-- AUTO-GENERATED from the @riverty/web-components custom elements manifest. Do not edit by hand. -->

# r-select

A select allows the user to choose between a set of options.
Overall behavior is based on native `<select>`

Example
```
<r-select name="country" label="Country" placeholder="Select a country">
  <r-select-option value="se">Sweden</r-select-option>
  <r-select-option value="no">Norway</r-select-option>
  <r-select-option value="dk">Denmark</r-select-option>
</r-select>
```

## class: `RSelect`, `r-select`

### Fields

| Name                    | Privacy | Type                | Default              | Description                                                                                                                                                                                                                                                              | Inherited From |
| ----------------------- | ------- | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `allowCustomValue`      |         | `boolean`           |                      | In combobox mode, allow the free-typed search text to become the value when<br>no option is selected. On collapse (other than Escape), the trimmed input<br>text is committed and `rChange` is emitted with `isCustom: true`.<br>No-op unless `combobox` is also set. |                |
| `combobox`              |         | `boolean`           |                      | Enable combobox functionality to allow users to reduce the list of options by filtering.                                                                                                                                                                                 |                |
| `customErrorMessage`    |         | `string`            |                      | Set custom message for `customError` property of a ValidityState object indicating whether the element's custom validity message has been set to a non-empty string by calling the element's setCustomValidity() method.                                                 |                |
| `disabled`              |         | `boolean`           |                      | Prevent user interaction and apply disabled style                                                                                                                                                                                                                        |                |
| `error`                 |         | `string`            |                      | Custom validation error message                                                                                                                                                                                                                                          |                |
| `expanded`              |         | `boolean`           |                      | Defines if select is expanded                                                                                                                                                                                                                                            |                |
| `fieldIndicator`        |         | `string`            |                      | Text of an additional marker in the label                                                                                                                                                                                                                                |                |
| `form`                  |         | `string`            |                      | Specifies the `id` of the `<form>` to which the element belongs                                                                                                                                                                                                          |                |
| `fullWidth`             |         | `boolean`           | `false`              | Define if select should render as a text item or a block                                                                                                                                                                                                                 |                |
| `hint`                  |         | `string`            |                      | Optional hint, visually presented under the select,<br>giving additional context to the user                                                                                                                                                                            |                |
| `internal`              |         | `boolean`           |                      | Specifies if the component is internal                                                                                                                                                                                                                                   |                |
| `invalid`               |         | `boolean`           |                      | Validity indicator, serving to change UI of the component                                                                                                                                                                                                                |                |
| `label`                 |         | `string`            |                      | The text on the label                                                                                                                                                                                                                                                    |                |
| `listboxPosition`       |         | `"bottom" \| "top"` | `'bottom'`           | Define wether listbox appears on top or at the bottom of the select                                                                                                                                                                                                      |                |
| `name`                  |         | `string`            |                      | Name of element (data) within a form                                                                                                                                                                                                                                     |                |
| `noResultsFound`        |         | `string`            | `'No results found'` | Defines the text that will be displayed if no results are found                                                                                                                                                                                                          |                |
| `novalidate`            |         | `boolean`           |                      | Specifies if element must be ignored during validation of the form elements                                                                                                                                                                                              |                |
| `placeholder`           |         | `string`            |                      | Text that is presented until an option has been selected                                                                                                                                                                                                                 |                |
| `readonly`              |         | `boolean`           |                      | Defines if select is in readonly state                                                                                                                                                                                                                                   |                |
| `required`              |         | `boolean`           |                      | Specifies that select value is required                                                                                                                                                                                                                                  |                |
| `toggleButtonAriaLabel` |         | `string`            | `'Toggle combobox'`  | Defines aria label for combobox toggle button                                                                                                                                                                                                                            |                |
| `valid`                 |         | `boolean`           |                      | Visual indication of valid state                                                                                                                                                                                                                                         |                |
| `value`                 |         | `string`            |                      | Selected value                                                                                                                                                                                                                                                           |                |
| `valueMissingMessage`   |         | `string`            |                      | Set custom message for `valueMissing` property of a ValidityState object (set by `required`) within Constrain Validation API                                                                                                                                             |                |

### Methods

| Name                | Privacy | Description                                                                                                                                                                                                                            | Parameters        | Return                              | Inherited From |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------------------- | -------------- |
| `checkValidity`     |         | Validates the textarea without triggering UI and returns a boolean indicating its validity.                                                                                                                                            |                   | `Promise<boolean>`                  |                |
| `clearReadonly`     |         | Clears readonly state from the component                                                                                                                                                                                               |                   | `Promise<void>`                     |                |
| `collapse`          |         | Collapse options listbox                                                                                                                                                                                                               |                   | `Promise<void>`                     |                |
| `expand`            |         | Expand options listbox                                                                                                                                                                                                                 |                   | `Promise<void>`                     |                |
| `getFocusedOption`  |         | Retrieves the currently focused option within this select component.<br><br>The focused option is identified by the presence of the `data-focused="true"`<br>attribute on an `r-select-option` element inside the component's host. |                   | `Promise<HTMLRSelectOptionElement>` |                |
| `getValue`          |         | Set value of the select                                                                                                                                                                                                                |                   | `Promise<string>`                   |                |
| `isDirty`           |         | Returns whether the select value has been changed by user interaction.                                                                                                                                                                 |                   | `Promise<boolean>`                  |                |
| `isTouched`         |         | Returns whether the select has been touched (focused/clicked by user).                                                                                                                                                                 |                   | `Promise<boolean>`                  |                |
| `markAsPristine`    |         | Marks the select as untouched and pristine (not dirty).                                                                                                                                                                                |                   | `Promise<void>`                     |                |
| `reportValidity`    |         | Check validity and reveal validation state and message                                                                                                                                                                                 |                   | `Promise<boolean>`                  |                |
| `reset`             |         | Reset select to its initial state                                                                                                                                                                                                      |                   | `Promise<void>`                     |                |
| `resetValidation`   |         | Clears validation results.                                                                                                                                                                                                             |                   | `Promise<void>`                     |                |
| `setBlur`           |         | Remove focus from the element                                                                                                                                                                                                          |                   | `Promise<void>`                     |                |
| `setCustomValidity` |         | Validates an element, displays provided message in case value is invalid.                                                                                                                                                              | `message: string` | `Promise<void>`                     |                |
| `setFocus`          |         | Set focus on the element                                                                                                                                                                                                               |                   | `Promise<void>`                     |                |
| `setFocusedOption`  |         | Sets focus to the option at the specified index.<br><br>Retrieves the option element from the internal optionElements collection<br>and delegates focusing logic to `setOptionFocus`.                                               | `index: any`      | `Promise<void>`                     |                |
| `setReadonly`       |         | Sets the component into `readonly` state                                                                                                                                                                                               |                   | `Promise<void>`                     |                |
| `setValue`          |         | Set value of the select programmatically.<br>Does NOT mark as dirty or emit change events.<br>Use this for programmatic value updates.                                                                                               | `value: string`   | `Promise<void>`                     |                |

### Events

| Name        | Type                                                                           | Description                                                    | Inherited From |
| ----------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------------- |
| `rBlur`     | `CustomEvent<any>`                                                             | Emitted when the select loses focus                            |                |
| `rChange`   | `CustomEvent<{ element: HTMLRSelectElement; value: any; isCustom: boolean; }>` | Emits `rChange` event when `<r-select>` value property changes |                |
| `rFocus`    | `CustomEvent<any>`                                                             | Emitted when the select receives focus                         |                |
| `rReset`    | `CustomEvent<{ element: HTMLRSelectElement; value: any; }>`                    | Emits `rReset` event when `<r-select>` onReset event happens   |                |
| `rValidate` | `CustomEvent<{ state: string; message: string; }>`                             | Emits event after each validation                              |                |

### Attributes

| Name                       | Field                 | Inherited From |
| -------------------------- | --------------------- | -------------- |
| `allow-custom-value`       | allowCustomValue      |                |
| `combobox`                 | combobox              |                |
| `custom-error-message`     | customErrorMessage    |                |
| `disabled`                 | disabled              |                |
| `error`                    | error                 |                |
| `expanded`                 | expanded              |                |
| `field-indicator`          | fieldIndicator        |                |
| `form`                     | form                  |                |
| `full-width`               | fullWidth             |                |
| `hint`                     | hint                  |                |
| `internal`                 | internal              |                |
| `invalid`                  | invalid               |                |
| `label`                    | label                 |                |
| `listbox-position`         | listboxPosition       |                |
| `name`                     | name                  |                |
| `no-results-found`         | noResultsFound        |                |
| `novalidate`               | novalidate            |                |
| `placeholder`              | placeholder           |                |
| `readonly`                 | readonly              |                |
| `required`                 | required              |                |
| `toggle-button-aria-label` | toggleButtonAriaLabel |                |
| `valid`                    | valid                 |                |
| `value`                    | value                 |                |
| `value-missing-message`    | valueMissingMessage   |                |

### CSS Parts

| Name      | Description                                     |
| --------- | ----------------------------------------------- |
| `label`   | label container for the select.                 |
| `message` | element that renders error messages.            |
| `options` | element that holds the option list content.     |
| `value`   | interactive element showing the selected value. |

### Slots

| Name      | Description                                                   |
| --------- | ------------------------------------------------------------- |
|           | Option items (`r-select-option` elements)                     |
| `leading` | Leading icon or element placed inside the trigger on the left |
| `popover` | Popover element attached to the label area                    |

<hr/>

## Exports

| Kind                        | Name       | Declaration | Module | Package |
| --------------------------- | ---------- | ----------- | ------ | ------- |
| `js`                        | `RSelect`  | RSelect     |        |         |
| `custom-element-definition` | `r-select` | RSelect     |        |         |