Select

Select widgets are Input Fields 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.

select.ts

import { gui } from '@golemui/gui-shared';

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

select.json

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "select",
      "path": "country",
      "label": "Country",
      "props": {
        "options": [
          {
            "label": "United States",
            "value": "us"
          },
          {
            "label": "Canada",
            "value": "ca"
          },
          {
            "label": "Mexico",
            "value": "mx"
          }
        ]
      }
    }
  ]
}

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.

select.ts

import { gui } from '@golemui/gui-shared';

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

select.json

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "select",
      "path": "country",
      "label": "Country",
      "props": {
        "placeholder": "Select your country",
        "options": [
          {
            "label": "United States",
            "value": "us"
          },
          {
            "label": "Canada",
            "value": "ca"
          }
        ]
      }
    }
  ]
}

Hint

Note

A label is required for the hint to be displayed.

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

select.ts

import { gui } from '@golemui/gui-shared';

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

select.json

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "select",
      "path": "country",
      "label": "Country",
      "props": {
        "hint": "Please select your current country of residence.",
        "options": [
          {
            "label": "United States",
            "value": "us"
          }
        ]
      }
    }
  ]
}

Icon

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

select.ts

import { gui } from '@golemui/gui-shared';

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

select.json

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "select",
      "path": "country",
      "label": "Country",
      "props": {
        "icon": "language",
        "options": [
          {
            "label": "United States",
            "value": "us"
          }
        ]
      }
    }
  ]
}

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.

select.ts

import { gui } from '@golemui/gui-shared';

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

select.json

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "select",
      "path": "country",
      "label": "Country",
      "props": {
        "labelField": "name",
        "valueField": "code",
        "options": [
          {
            "name": "United States",
            "code": "us"
          },
          {
            "name": "Canada",
            "code": "ca"
          }
        ]
      }
    }
  ]
}

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.

select.ts

import { gui } from '@golemui/gui-shared';

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',
  }),
];

select.json

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "select",
      "path": "country",
      "label": "Country",
      "defaultValue": "fr",
      "props": {
        "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"
      }
    }
  ]
}

Styling

Select widgets can be styled as explained in the Styling Guide.

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.

select-anatomy.html

<gui-select>
  <label for="fieldUid">
    Label
    <div class="gui-select__hint" id="fieldUid_hint">Hint</div>
  </label>

  <div class="gui-widget">
    <select
      id="fieldUid"
      class="gui-select-input gui-select--icon"
      aria-required="true"
      aria-describedby="fieldUid_hint"
    >
      <option value="" disabled selected>
        Select an option
      </option>
      <option value="us">United States</option>
      <option value="ca">Canada</option>
    </select>
    <span class="gui-widget-icon fas fa-globe"></span>
  </div>
</gui-select>