Dropdown

Dropdown widgets are Input Fields that provide a searchable list of items. Users can either type in the input to filter the list or select an item directly from the interactive dropdown menu.

The simplest way to populate items is a flat array of strings or numbers — the displayed label and the stored value are the same. When you need a separate stored value (e.g. an id behind a human-readable name), pass an array of objects and tell the widget which keys to use via labelField and valueField.

dropdown.ts

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

export default [
  gui.inputs.dropdown('selection', {
    items: ['Apple', 'Banana', 'Cherry'],
    placeholder: 'Type to search...',
    label: 'Select an Item',
    uid: 'dropdown_id',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_id",
      "kind": "input",
      "type": "dropdown",
      "path": "selection",
      "label": "Select an Item",
      "props": {
        "items": ["Apple", "Banana", "Cherry"],
        "placeholder": "Type to search..."
      }
    }
  ]
}

Props

Use these props to customize your Dropdown widget.

prop	type	description
items	array	Required. Array of strings, numbers, or plain objects. See Using Objects.
placeholder	string	Text shown in the input when it is empty
hint	string	A description to display below the input
labelField	string	When items are objects, the key whose value is shown to the user. Defaults to label.
valueField	string	When items are objects, the key whose value is stored in the form. Defaults to value. Required for selection to emit a primitive.
searchFields	array	List of fields to search on when filtering the list
height	number	Height of the dropdown list container
itemHeight	number	Height of each individual item in the list
itemRenderer	string	Key of a registered renderer used to draw each item. See Item Renderers
inputDebounce	number	Delay in milliseconds before triggering a search/filter. Defaults to 500
autocomplete	string	'on', 'off', or a space-separated list of W3C autofill tokens

Using Objects

The top-of-page demo uses an array of strings — each entry is both what the user sees and what gets stored. That’s enough for many forms, but it falls short when you need to keep a stable id behind a human-readable label (e.g. a country code paired with a country name).

For that case, pass items as plain objects and use labelField and valueField to tell the widget which key holds the displayed text and which one holds the stored value. The example below pairs each country name with a short code, and searchFields lets the user filter by either.

dropdown.ts

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

export default [
  gui.inputs.dropdown('selection', {
    items: [
      { name: 'USA', code: 'US' },
      { name: 'Canada', code: 'CA' },
    ],
    labelField: 'name',
    valueField: 'code',
    searchFields: ['name', 'code'],
    label: 'Custom Fields',
    uid: 'dropdown_custom',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_custom",
      "kind": "input",
      "type": "dropdown",
      "path": "selection",
      "label": "Custom Fields",
      "props": {
        "items": [
          { "name": "USA", "code": "US" },
          { "name": "Canada", "code": "CA" }
        ],
        "labelField": "name",
        "valueField": "code",
        "searchFields": ["name", "code"]
      }
    }
  ]
}

If your objects already use the default key names (label and value), you can omit labelField and valueField entirely. Otherwise both should be set so selection can extract the right primitive.

Hint

Note

A label is required for the hint to be displayed.

Use the property hint to provide instructions for the user.

dropdown.ts

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

export default [
  gui.inputs.dropdown('selection', {
    items: ['Apple', 'Banana'],
    hint: 'Start typing to filter the available items',
    label: 'Select an Item',
    uid: 'dropdown_hint',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_hint",
      "kind": "input",
      "type": "dropdown",
      "path": "selection",
      "label": "Select an Item",
      "props": {
        "items": ["Apple", "Banana"],
        "hint": "Start typing to filter the available items"
      }
    }
  ]
}

Item Renderer

Use the property itemRenderer to draw each row with a registered renderer instead of the default template. The key must match one of the renderers registered on the form host — see Item Renderers for the full setup.

This demo uses the registered countryItemRenderer to display each country with its flag.

dropdown.ts

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

export default [
  gui.inputs.dropdown('country', {
    items: [
      { id: 'AU', flag: '🇦🇺', label: 'Australia' },
      { id: 'BR', flag: '🇧🇷', label: 'Brazil' },
      { id: 'CA', flag: '🇨🇦', label: 'Canada' },
      { id: 'FR', flag: '🇫🇷', label: 'France' },
      { id: 'DE', flag: '🇩🇪', label: 'Germany' },
      { id: 'JP', flag: '🇯🇵', label: 'Japan' },
      { id: 'ES', flag: '🇪🇸', label: 'Spain' },
      { id: 'US', flag: '🇺🇸', label: 'United States' },
      { id: 'GB', flag: '🇬🇧', label: 'United Kingdom' },
    ],
    labelField: 'label',
    valueField: 'id',
    searchFields: ['label'],
    itemRenderer: 'countryItemRenderer',
    label: 'Pick a country',
    uid: 'dropdown_item_renderer',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_item_renderer",
      "kind": "input",
      "type": "dropdown",
      "path": "country",
      "label": "Pick a country",
      "props": {
        "labelField": "label",
        "valueField": "id",
        "searchFields": ["label"],
        "itemRenderer": "countryItemRenderer",
        "items": [
          { "id": "AU", "flag": "🇦🇺", "label": "Australia" },
          { "id": "BR", "flag": "🇧🇷", "label": "Brazil" },
          { "id": "CA", "flag": "🇨🇦", "label": "Canada" },
          { "id": "FR", "flag": "🇫🇷", "label": "France" },
          { "id": "DE", "flag": "🇩🇪", "label": "Germany" },
          { "id": "JP", "flag": "🇯🇵", "label": "Japan" },
          { "id": "ES", "flag": "🇪🇸", "label": "Spain" },
          { "id": "US", "flag": "🇺🇸", "label": "United States" },
          { "id": "GB", "flag": "🇬🇧", "label": "United Kingdom" }
        ]
      }
    }
  ]
}

Size

Use height to set the size of the dropdown’s scrollable list, and itemHeight to fix the row height used by the virtual scroller. Tune itemHeight whenever you use a custom itemRenderer whose rows are taller than the default.

dropdown.ts

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

export default [
  gui.inputs.dropdown('selection', {
    items: ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'],
    hint: 'Open the dropdown to see the taller list with larger rows',
    height: 200,
    itemHeight: 56,
    label: 'Pick a number',
    uid: 'dropdown_size',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_size",
      "kind": "input",
      "type": "dropdown",
      "path": "selection",
      "label": "Pick a number",
      "props": {
        "hint": "Open the dropdown to see the taller list with larger rows",
        "height": 200,
        "itemHeight": 56,
        "items": ["One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight"]
      }
    }
  ]
}

Input Debounce

Use inputDebounce to control how long the dropdown waits after each keystroke before applying the filter. Useful when the filter event triggers a server-side search.

dropdown.ts

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

export default [
  gui.inputs.dropdown('fruit', {
    items: [
      'Apple',
      'Apricot',
      'Banana',
      'Blueberry',
      'Cherry',
      'Grapefruit',
      'Mango',
      'Orange',
      'Peach',
      'Pineapple',
    ],
    hint: 'Filtering waits 800ms after the last keystroke',
    inputDebounce: 800,
    label: 'Pick a fruit',
    uid: 'dropdown_debounce',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_debounce",
      "kind": "input",
      "type": "dropdown",
      "path": "fruit",
      "label": "Pick a fruit",
      "props": {
        "hint": "Filtering waits 800ms after the last keystroke",
        "inputDebounce": 800,
        "items": [
          "Apple",
          "Apricot",
          "Banana",
          "Blueberry",
          "Cherry",
          "Grapefruit",
          "Mango",
          "Orange",
          "Peach",
          "Pineapple"
        ]
      }
    }
  ]
}

Autocomplete

Use autocomplete to set the underlying input’s autocomplete attribute. Accepts 'on', 'off', or a space-separated list of W3C autofill tokens.

dropdown.ts

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

export default [
  gui.inputs.dropdown('country', {
    items: [
      { name: 'France', code: 'FR' },
      { name: 'Germany', code: 'DE' },
      { name: 'Spain', code: 'ES' },
      { name: 'United Kingdom', code: 'GB' },
      { name: 'United States', code: 'US' },
    ],
    autocomplete: 'country-name',
    labelField: 'name',
    valueField: 'code',
    searchFields: ['name'],
    label: 'Country',
    uid: 'dropdown_autocomplete',
  }),
];

dropdown.json

{
  "form": [
    {
      "uid": "dropdown_autocomplete",
      "kind": "input",
      "type": "dropdown",
      "path": "country",
      "label": "Country",
      "props": {
        "autocomplete": "country-name",
        "labelField": "name",
        "valueField": "code",
        "searchFields": ["name"],
        "items": [
          { "name": "France", "code": "FR" },
          { "name": "Germany", "code": "DE" },
          { "name": "Spain", "code": "ES" },
          { "name": "United Kingdom", "code": "GB" },
          { "name": "United States", "code": "US" }
        ]
      }
    }
  ]
}

Styling

Dropdowns can be styled as explained in the Styling Guide.

CSS Variables

Dropdowns leverage standard container and list variables.

CSS Variable	Description
--gui-radius-md	Border radius for the container
--gui-border-default	Default border color

Anatomy

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

dropdown-anatomy.html

<div class="gui-dropdown">
  <gui-label>
    <label for="dropdown_id">Select an Item</label>
    <div class="gui-label__hint">Type to search...</div>
  </gui-label>

  <div class="gui-widget">
    <input type="text" id="dropdown_id" placeholder="Type to search..." />

    <gui-list>
      <div class="gui-list__container">
        <div class="gui-list__item-wrapper" role="option" aria-selected="false">
          <div class="gui-list-item">Apple</div>
        </div>
        <div class="gui-list__item-wrapper" role="option" aria-selected="false">
          <div class="gui-list-item">Banana</div>
        </div>
      </div>
    </gui-list>
  </div>
</div>