List

List widgets 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.

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.

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

export default [
  gui.inputs.list('selection', {
    items: ['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5'],
    height: 200,
    itemHeight: 40,
    label: 'Pick an option',
    uid: 'list_id',
  }),
];

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

Props

Use these props to customize your List widget.

prop	type	description
`items`	array	Required. Array of strings, numbers, or plain objects. See Using Objects.
`hint`	string	A description to display below the list
`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.
`height`	number	Total height of the scrollable viewport. Defaults to `300`
`itemHeight`	number	Fixed height of each item for virtualization logic. Defaults to `40`
`itemRenderer`	string	Key of a registered renderer used to draw each item. See Item Renderers

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 when label and value are identical, but lists are often backed by domain data where the human-readable name and the stored identifier differ.

For that case, pass items as plain objects and use labelField and valueField to tell the list which key holds the displayed text and which one holds the stored value.

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

export default [
  gui.inputs.list('selection', {
    items: [
      { name: 'USA', code: 'US' },
      { name: 'Canada', code: 'CA' },
      { name: 'Mexico', code: 'MX' },
      { name: 'Brazil', code: 'BR' },
      { name: 'Argentina', code: 'AR' },
    ],
    height: 200,
    itemHeight: 40,
    labelField: 'name',
    valueField: 'code',
    label: 'Custom Fields',
    uid: 'list_custom',
  }),
];

{
  "form": [
    {
      "uid": "list_custom",
      "kind": "input",
      "type": "list",
      "path": "selection",
      "label": "Custom Fields",
      "props": {
        "height": 200,
        "itemHeight": 40,
        "labelField": "name",
        "valueField": "code",
        "items": [
          { "name": "USA", "code": "US" },
          { "name": "Canada", "code": "CA" },
          { "name": "Mexico", "code": "MX" },
          { "name": "Brazil", "code": "BR" },
          { "name": "Argentina", "code": "AR" }
        ]
      }
    }
  ]
}

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

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

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

export default [
  gui.inputs.list('selection', {
    items: ['Option A', 'Option B'],
    hint: 'Please select one of the available choices from the list.',
    label: 'Pick an option',
    uid: 'list_hint',
  }),
];

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

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 complexListItemRenderer to display a title and description per row. Bump itemHeight to match the renderer’s row height so virtualization stays accurate.

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

export default [
  gui.inputs.list('selection', {
    items: [
      {
        value: 'blog',
        title: 'Blog',
        description: 'A minimalist Markdown blog with RSS feed and dark mode.',
      },
      {
        value: 'docs',
        title: 'Documentation Site',
        description: 'Versioned docs with full-text search and a live playground.',
      },
      {
        value: 'dashboard',
        title: 'Admin Dashboard',
        description: 'Data tables, charts, and role-based auth out of the box.',
      },
      {
        value: 'storefront',
        title: 'E-commerce Storefront',
        description: 'Product catalog, cart, and Stripe checkout wired up.',
      },
      {
        value: 'landing',
        title: 'Marketing Landing',
        description: 'Hero, pricing tiers, and a contact form ready to ship.',
      },
      {
        value: 'portfolio',
        title: 'Developer Portfolio',
        description: 'Showcase projects, embed demos, and host a personal blog.',
      },
    ],
    height: 240,
    itemHeight: 60,
    labelField: 'title',
    valueField: 'value',
    itemRenderer: 'complexListItemRenderer',
    label: 'Pick a starter template',
    uid: 'list_item_renderer',
  }),
];

{
  "form": [
    {
      "uid": "list_item_renderer",
      "kind": "input",
      "type": "list",
      "path": "selection",
      "label": "Pick a starter template",
      "props": {
        "height": 240,
        "itemHeight": 60,
        "labelField": "title",
        "valueField": "value",
        "itemRenderer": "complexListItemRenderer",
        "items": [
          {
            "value": "blog",
            "title": "Blog",
            "description": "A minimalist Markdown blog with RSS feed and dark mode."
          },
          {
            "value": "docs",
            "title": "Documentation Site",
            "description": "Versioned docs with full-text search and a live playground."
          },
          {
            "value": "dashboard",
            "title": "Admin Dashboard",
            "description": "Data tables, charts, and role-based auth out of the box."
          },
          {
            "value": "storefront",
            "title": "E-commerce Storefront",
            "description": "Product catalog, cart, and Stripe checkout wired up."
          },
          {
            "value": "landing",
            "title": "Marketing Landing",
            "description": "Hero, pricing tiers, and a contact form ready to ship."
          },
          {
            "value": "portfolio",
            "title": "Developer Portfolio",
            "description": "Showcase projects, embed demos, and host a personal blog."
          }
        ]
      }
    }
  ]
}

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 Widget in case you want to use your CSS styles.

<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>