Skip to content

Item Renderers

Some widgets render a list of items — dropdown, list, radiogroup, and similar. By default, each item is rendered as a label/value pair. Item renderers let you supply a richer template (e.g. a country flag next to its label, a product card with a thumbnail and a price).

An item renderer is a small framework-specific function or component that receives the current item and returns the template for it. The renderer is registered under a name; widgets reference that name through their itemRenderer prop.

The shape of CountryItemRenderer itself is framework-specific — see Extending GolemUI / Item Renderers for the implementation contract. The wiring below shows how to register and use it once it exists.

Wiring an item renderer

In the Programmatic API, item renderers go inside formConfig.itemRenderers. The widget references the renderer by name through its itemRenderer prop.

import { gui } from '@golemui/gui-shared';
import { GuiForm } from '@golemui/gui-react';
import { CountryItemRenderer } from './CountryItemRenderer';

const config = {
  formDef: [
    gui.inputs.dropdown('country', {
      items: [
        { id: 'US', flag: '🇺🇸', label: 'United States' },
        { id: 'CA', flag: '🇨🇦', label: 'Canada' },
      ],
      labelField: 'label',
      valueField: 'id',
      itemRenderer: 'countryItemRenderer',
    }),
  ],
  formConfig: { itemRenderers: { countryItemRenderer: CountryItemRenderer } },
};

export function MyForm() {
  return <GuiForm config={config} />;
}

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { gui } from '@golemui/gui-shared';
import { FormComponent } from '@golemui/gui-angular';
import { CountryItemRenderer } from './country-item-renderer.component';

@Component({
  imports: [CommonModule, FormComponent],
  selector: 'app-my-form',
  template: `<gui-form [config]="config"></gui-form>`,
})
export class MyForm {
  protected config = {
    formDef: [
      gui.inputs.dropdown('country', {
        items: [
          { id: 'US', flag: '🇺🇸', label: 'United States' },
          { id: 'CA', flag: '🇨🇦', label: 'Canada' },
        ],
        labelField: 'label',
        valueField: 'id',
        itemRenderer: 'countryItemRenderer',
      }),
    ],
    formConfig: {
      itemRenderers: { countryItemRenderer: CountryItemRenderer },
    },
  };
}

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { gui } from '@golemui/gui-shared';
import '@golemui/gui-lit';
import { countryItemRenderer } from './country-item-renderer';

@customElement('my-form')
export class MyForm extends LitElement {
  config = {
    formDef: [
      gui.inputs.dropdown('country', {
        items: [
          { id: 'US', flag: '🇺🇸', label: 'United States' },
          { id: 'CA', flag: '🇨🇦', label: 'Canada' },
        ],
        labelField: 'label',
        valueField: 'id',
        itemRenderer: 'countryItemRenderer',
      }),
    ],
    formConfig: {
      itemRenderers: { countryItemRenderer },
    },
  };

  override createRenderRoot() { return this; }

  override render() {
    return html`<gui-form .config=${this.config}></gui-form>`;
  }
}

<script setup lang="ts">
import { gui } from '@golemui/gui-shared';
import { GuiForm } from '@golemui/gui-vue';
import CountryItemRenderer from './CountryItemRenderer.vue';

const config = {
  formDef: [
    gui.inputs.dropdown('country', {
      items: [
        { id: 'US', flag: '🇺🇸', label: 'United States' },
        { id: 'CA', flag: '🇨🇦', label: 'Canada' },
      ],
      labelField: 'label',
      valueField: 'id',
      itemRenderer: 'countryItemRenderer',
    }),
  ],
  formConfig: {
    itemRenderers: { countryItemRenderer: CountryItemRenderer },
  },
};
</script>

<template>
  <GuiForm :config="config" />
</template>

import '@golemui/gui-components/index.css';
import '@golemui/gui-lit';
import { gui } from '@golemui/gui-shared';
import { countryItemRenderer } from './country-item-renderer';

const config = {
  formDef: [
    gui.inputs.dropdown('country', {
      items: [
        { id: 'US', flag: '🇺🇸', label: 'United States' },
        { id: 'CA', flag: '🇨🇦', label: 'Canada' },
      ],
      labelField: 'label',
      valueField: 'id',
      itemRenderer: 'countryItemRenderer',
    }),
  ],
  formConfig: {
    itemRenderers: { countryItemRenderer },
  },
};

const form = document.getElementById('app-form');
form.config = config;

In the JSON path, item renderers go into the itemRenderers property on the config object. The JSON references the renderer by name through the dropdown’s "itemRenderer" field.

{
  "form": [
    {
      "kind": "input",
      "type": "dropdown",
      "path": "country",
      "items": [
        { "id": "US", "flag": "🇺🇸", "label": "United States" },
        { "id": "CA", "flag": "🇨🇦", "label": "Canada" }
      ],
      "labelField": "label",
      "valueField": "id",
      "itemRenderer": "countryItemRenderer"
    }
  ]
}

import { GuiForm } from '@golemui/gui-react';
import formDef from './my-form.json';
import { CountryItemRenderer } from './CountryItemRenderer';

const config = {
  formDef,
  itemRenderers: { countryItemRenderer: CountryItemRenderer },
};

export function MyForm() {
  return <GuiForm config={config} />;
}

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { FormComponent } from '@golemui/gui-angular';
import { CountryItemRenderer } from './country-item-renderer.component';
import formDef from './my-form.json';

@Component({
  imports: [CommonModule, FormComponent],
  selector: 'app-my-form',
  template: `<gui-form [config]="config"></gui-form>`,
})
export class MyForm {
  protected config = {
    formDef,
    itemRenderers: { countryItemRenderer: CountryItemRenderer },
  };
}

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-lit';
import { countryItemRenderer } from './country-item-renderer';
import formDef from './my-form.json';

@customElement('my-form')
export class MyForm extends LitElement {
  config = {
    formDef,
    itemRenderers: { countryItemRenderer },
  };

  override createRenderRoot() { return this; }

  override render() {
    return html`<gui-form .config=${this.config}></gui-form>`;
  }
}

<script setup lang="ts">
import { GuiForm } from '@golemui/gui-vue';
import CountryItemRenderer from './CountryItemRenderer.vue';
import formDef from './my-form.json';

const config = {
  formDef,
  itemRenderers: { countryItemRenderer: CountryItemRenderer },
};
</script>

<template>
  <GuiForm :config="config" />
</template>

import '@golemui/gui-components/index.css';
import '@golemui/gui-lit';
import formDef from './my-form.json';
import { countryItemRenderer } from './country-item-renderer';

const config = {
  formDef,
  itemRenderers: { countryItemRenderer },
};

const form = document.getElementById('app-form');
form.config = config;

See also

Extending GolemUI / Item Renderers — implementing renderers per framework.
Widgets Reference / Dropdown — every prop a dropdown supports.