# Select

> A Select widget to allow user to pick one option from a dropdown menu using the native select behavior

Select widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) that allow users to pick a single item from a predefined list of options. They use the native HTML `<select>` element to provide familiar interaction patterns, especially on mobile devices.


```ts title="select.ts"

export default [
  gui.inputs.select('country', {
    options: [
      {
        label: 'United States',
        value: 'us',
      },
      {
        label: 'Canada',
        value: 'ca',
      },
      {
        label: 'Mexico',
        value: 'mx',
      },
    ],
    label: 'Country',
  }),
];
```

_Live demo on the docs page. Form definition: [select.ts](https://golemui.com/template/widgets-dx/select/select.ts)._

## Props

Use these `props` to customize your Select widget.

| prop                   | type                  | description                                                                                                                      |
| ---------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `options`              | array                 | **Required**. Array of objects representing the dropdown choices                                                                 |
| `autocomplete`         | string                | `'on'`, `'off'`, or a space-separated list of W3C autofill tokens                                                                |
| `hint`                 | string                | A description to display below the select dropdown                                                                               |
| `icon`                 | string                | Custom icon class to display inside the select box (e.g. `fas fa-globe`)                                                         |
| `invalidOptionMessage` | string \| Localizable | Error message shown when the bound value is not one of the options; a `{value}` placeholder is replaced with the offending value |
| `labelField`           | string                | Which object key to use as the display label for an option. Defaults to `label`                                                  |
| `placeholder`          | string                | Text shown when no option is selected. Defaults to "Select an option"                                                            |
| `valueField`           | string                | Which object key to use as the underlying value for an option. Defaults to `value`                                               |

### Placeholder

Use the property `placeholder` to define the default empty-state text.


```ts title="select.ts"

export default [
  gui.inputs.select('country', {
    placeholder: 'Select your country',
    options: [
      {
        label: 'United States',
        value: 'us',
      },
      {
        label: 'Canada',
        value: 'ca',
      },
    ],
    label: 'Country',
  }),
];
```

_Live demo on the docs page. Form definition: [select-placeholder.ts](https://golemui.com/template/widgets-dx/select/select-placeholder.ts)._

### Hint

<Aside>A `label` is required for the `hint` to be displayed.</Aside>

Use the property `hint` to add descriptive text or validation instructions.


```ts title="select.ts"

export default [
  gui.inputs.select('country', {
    hint: 'Please select your current country of residence.',
    options: [
      {
        label: 'United States',
        value: 'us',
      },
    ],
    label: 'Country',
  }),
];
```

_Live demo on the docs page. Form definition: [select-hint.ts](https://golemui.com/template/widgets-dx/select/select-hint.ts)._

### Icon

Use the property `icon` to add a visual indicator inside the select input, on the left side.


```ts title="select.ts"

export default [
  gui.inputs.select('country', {
    icon: 'language',
    options: [
      {
        label: 'United States',
        value: 'us',
      },
    ],
    label: 'Country',
  }),
];
```

_Live demo on the docs page. Form definition: [select-icon.ts](https://golemui.com/template/widgets-dx/select/select-icon.ts)._

### Custom Option Fields

If your data source uses different keys for the label and value (e.g., `name` and `code`), use `labelField` and `valueField` to map them accordingly.


```ts title="select.ts"

export default [
  gui.inputs.select('country', {
    labelField: 'name',
    valueField: 'code',
    options: [
      {
        name: 'United States',
        code: 'us',
      },
      {
        name: 'Canada',
        code: 'ca',
      },
    ],
    label: 'Country',
  }),
];
```

_Live demo on the docs page. Form definition: [select-custom-fields.ts](https://golemui.com/template/widgets-dx/select/select-custom-fields.ts)._

### Invalid Option

Use the property `invalidOptionMessage` to customize (and localize) the error shown when the bound value is not one of the `options`. A `{value}` placeholder in the message is replaced with the offending value.


```ts title="select.ts"

export default [
  gui.inputs.select('country', {
    hint: 'The bound value "fr" is not among the options',
    options: [
      {
        label: 'United States',
        value: 'us',
      },
      {
        label: 'Canada',
        value: 'ca',
      },
      {
        label: 'Mexico',
        value: 'mx',
      },
    ],
    invalidOptionMessage: '"{value}" is not a selectable country',
    label: 'Country',
    defaultValue: 'fr',
  }),
];
```

_Live demo on the docs page. Form definition: [select-invalidoption.ts](https://golemui.com/template/widgets-dx/select/select-invalidoption.ts)._

## Styling

Select widgets can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md).

### CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

| CSS Variable             | Description                                |
| ------------------------ | ------------------------------------------ |
| `--gui-text-default`     | Dropdown arrow indicator color             |
| `--gui-space-gap--inner` | Label gap                                  |
| `--gui-intent-error`     | Border and focus shadow color when invalid |

### Anatomy

This is the anatomy of the Select Widget in case you want to use your CSS styles.


```html title="select-anatomy.html"
<gui-select-input class="gui-select gui-field">
  <gui-select class="gui-field">
    <label class="gui-label" for="fieldUid" id="fieldUid_label">
      <span class="gui-label__text">Label</span>
      <div class="gui-widget-hint" id="fieldUid_hint" aria-hidden="true">Hint</div>
    </label>

    <div class="gui-widget">
      <select
        id="fieldUid"
        class="gui-widget-input gui-select--icon"
        aria-describedby="fieldUid_hint"
      >
        <option value="" disabled="">Custom placeholder</option>
        <option value="us">United States</option>
        <option value="ca">Canada</option>
        <option value="mx">Mexico</option>
      </select>
      <span class="gui-select__arrow"><span class="gui-caret" aria-hidden="true"></span></span>
      <span aria-hidden="true" class="gui-widget-icon language" data-icon="language"></span>
    </div>

    <div class="gui-validator gui-validator--empty" id="fieldUid_errors" role="alert"></div>
  </gui-select>
</gui-select-input>
```
