List

List components are Input Fields designed to handle selection from potentially thousands of items efficiently. They use virtualization to only render the items currently visible in the viewport, ensuring high performance regardless of the total data volume.

Programmatic

list.ts

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

export default golemForm().create({
  form: [
    {
      uid: 'list_id',
      kind: 'input',
      type: 'list',
      path: 'selection',
      label: 'Pick an option',
      props: {
        items: [
          {
            template: 'Option 1',
            value: '1',
          },
          {
            template: 'Option 2',
            value: '2',
          },
          {
            template: 'Option 3',
            value: '3',
          },
          {
            template: 'Option 4',
            value: '4',
          },
          {
            template: 'Option 5',
            value: '5',
          },
        ],
        height: 200,
        itemHeight: 40,
      },
    },
  ],
});

JSON

list.json

{
  "form": [
    {
      "uid": "list_id",
      "kind": "input",
      "type": "list",
      "path": "selection",
      "label": "Pick an option",
      "props": {
        "items": [
          { "template": "Option 1", "value": "1" },
          { "template": "Option 2", "value": "2" },
          { "template": "Option 3", "value": "3" },
          { "template": "Option 4", "value": "4" },
          { "template": "Option 5", "value": "5" }
        ],
        "height": 200,
        "itemHeight": 40
      }
    }
  ]
}

Props

Use these props to customize your List component.

prop	type	description
items	array	Required. Collection of items. Can be strings, numbers, or objects
value	string | number	The currently selected value
valueField	string	The key to use for the value if items are objects
height	number	Total height of the scrollable viewport. Defaults to 300
itemHeight	number	Fixed height of each item for virtualization logic. Defaults to 40
hint	string	A description to display for accessibility
itemRenderer	string	Key or identifier for a custom item renderer

Hint

Note

A label is required for the hint to be displayed.

Use the property hint to provide additional context for the list.

Programmatic

list.ts

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

export default golemForm().create({
  form: [
    {
      uid: 'list_hint',
      kind: 'input',
      type: 'list',
      path: 'selection',
      label: 'Pick an option',
      props: {
        items: [
          {
            template: 'Option A',
            value: 'a',
          },
          {
            template: 'Option B',
            value: 'b',
          },
        ],
        hint: 'Please select one of the available choices from the list.',
      },
    },
  ],
});

JSON

list.json

{
  "form": [
    {
      "uid": "list_hint",
      "kind": "input",
      "type": "list",
      "path": "selection",
      "label": "Pick an option",
      "props": {
        "items": [
          { "template": "Option A", "value": "a" },
          { "template": "Option B", "value": "b" }
        ],
        "hint": "Please select one of the available choices from the list."
      }
    }
  ]
}

Styling

Lists 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-bg-default	Background color for the list container
--gui-border-default	Border color for the list container
--gui-radius-md	Border radius for the list container
--gui-intent-primary	Background color for the selected item
--gui-intent-primary-hover	Background color for items on hover
--gui-bg-disabled	Background color for disabled items

Anatomy

This is the anatomy of the List Component in case you want to use your CSS styles.

list-anatomy.html

<gui-list>
  <div
    role="listbox"
    class="gui-list__scroll-viewport"
    style="height: 200px; overflow-y: auto; position: relative;"
  >
    <div class="gui-list__spacer" style="height: 200px;"></div>

    <div class="gui-list__content" style="transform: translateY(0px); position: absolute; top: 0; left: 0; width: 100%;">

      <div class="gui-list__item-wrapper" role="option" aria-selected="true" id="list_id-item-0">
        <div class="gui-list__item gui-list__item-selected">Option 1</div>
      </div>

      <div class="gui-list__item-wrapper" role="option" aria-selected="false" id="list_id-item-1">
        <div class="gui-list__item">Option 2</div>
      </div>

      <!-- More items -->

    </div>
  </div>
</gui-list>