Creating an input widget

An input widget binds to a path in the form data, supports validation, and tracks touched state. The framework helpers (useInputWidget in React and Vue, InputWidgetAdapter in Angular and Lit) handle data binding for you — your widget calls a few methods, the engine does the rest. The example we’ll walk through is productRating — a star-based rating control.

Widget definition

The maxRating prop controls how many stars are displayed. The path ('product.rating') tells the form engine where to store the selected value (a number from 1 to maxRating). The validator adds built-in number validation — in this case, making the field required.

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

gui.inputs.custom('productRating', 'product.rating', {
  maxRating: 10,
  validator: { type: 'number', required: true },
});

{
  "kind": "input",
  "type": "productRating",
  "path": "product.rating",
  "props": { "maxRating": 10 },
  "validator": { "type": "number", "required": true }
}

API summary

Method	Purpose
onValueChanged(value)	Update the form data at the widget’s path.
onBlur()	Mark the field as touched and trigger blur-time validation.
templateData.errors	Array of validation error messages for this field.
templateData.touched	Whether the user has interacted with the field.
injectValidationIssues(issues)	Programmatically inject custom validation errors.

Implementation

React

Key concepts (React)

• useInputWidget returns the typed value, errors, isTouched, and a merged templateData (your custom props + engine-managed values).
• Call onValueChanged(newValue) from a click/change handler — the engine writes through to the form data and runs validation.
• Call onBlur() when the user leaves the field. With validateOn: 'blur' (or 'eager'), this triggers validation; either way, it sets isTouched.
• style={{ flex: templateData.size }} lets the input participate in flex parents — see Sizing custom widgets for the rationale.

ProductRating.tsx

import type { InputWidget, WithWidget } from '@golemui/core';
import { useInputWidget } from '@golemui/react';

interface ProductRatingProps {
  maxRating: number;
}

export function ProductRating(widgetInstance: WithWidget) {
  const widget = widgetInstance.widget as InputWidget<number>;
  const { uid, value, errors, isTouched, templateData, onValueChanged, onBlur } =
    useInputWidget<number, ProductRatingProps>(widget);

  const maxRating = templateData.maxRating || 5;

  return (
    <div className="product-rating" style={{ flex: templateData.size }}>
      <div className="product-rating__widget" id={uid}>
        <div className="product-rating__stars" onBlur={onBlur} tabIndex={0}>
          {Array.from({ length: maxRating }, (_, i) => i + 1).map((star) => (
            <span
              key={star}
              role="button"
              className={`product-rating__star ${
                star <= (value || 0) ? 'product-rating__star--active' : ''
              }`}
              onClick={() => onValueChanged(star)}
            >
              {star <= (value || 0) ? '★' : '☆'}
            </span>
          ))}
        </div>
        {isTouched && errors.length > 0 && (
          <div className="product-rating__errors">
            {errors.map((error, i) => (
              <span key={i} className="product-rating__error">{error}</span>
            ))}
          </div>
        )}
      </div>
    </div>
  );
}

Angular

Key concepts (Angular)

• Provide InputWidgetAdapter in the component’s providers, then init() it in ngOnInit and destroy() it in ngOnDestroy. The adapter’s templateData() signal exposes value, errors, touched, plus your custom props.
• Call this.adapter.valueChanged(newValue) to write through to the form data and trigger validation.
• Call this.adapter.onBlur() from a (blur) handler to mark the field touched and run blur-time validation.
• The host binding '[style.flex]': 'this.adapter.templateData().size' lets the input participate in flex parents — see Sizing custom widgets for the rationale.

product-rating.component.ts

import { CommonModule } from '@angular/common';
import { Component, inject, OnDestroy, OnInit } from '@angular/core';
import { InputWidgetAdapter } from '@golemui/angular';
import type { InputWidget, WithWidget } from '@golemui/core';

interface ProductRatingProps {
  maxRating: number;
}

@Component({
  standalone: true,
  selector: 'app-product-rating',
  imports: [CommonModule],
  providers: [InputWidgetAdapter],
  host: {
    class: 'product-rating',
    '[style.flex]': 'this.adapter.templateData().size',
  },
  template: `
    @let templateData = adapter.templateData();
    @let maxRating = templateData.maxRating || 5;

    <div class="product-rating__widget" [id]="widget.uid">
      <div class="product-rating__stars" (blur)="onBlur()" tabindex="0">
        @for (star of stars(maxRating); track star) {
          <span
            role="button"
            class="product-rating__star"
            [class.product-rating__star--active]="star <= (templateData.value || 0)"
            (click)="selectRating(star)"
          >
            {{ star <= (templateData.value || 0) ? '★' : '☆' }}
          </span>
        }
      </div>
      @if (templateData.touched && templateData.errors?.length) {
        <div class="product-rating__errors">
          @for (error of templateData.errors; track error) {
            <span class="product-rating__error">{{ error }}</span>
          }
        </div>
      }
    </div>
  `,
})
export class ProductRatingComponent
  implements OnInit, OnDestroy, WithWidget
{
  widget!: InputWidget<number>;

  protected adapter: InputWidgetAdapter<number, ProductRatingProps> =
    inject(InputWidgetAdapter);

  ngOnInit(): void {
    this.adapter.init(this.widget);
  }

  ngOnDestroy(): void {
    this.adapter.destroy();
  }

  stars(count: number): number[] {
    return Array.from({ length: count }, (_, i) => i + 1);
  }

  selectRating(star: number): void {
    this.adapter.valueChanged(star);
  }

  onBlur(): void {
    this.adapter.onBlur();
  }
}

Lit

Key concepts (Lit)

• Consume formContext and provide inputContext so any nested widget can resolve through the registry.
• Subscribe to adapter.templateDataChanged$ to drive Lit’s requestUpdate(). Clean up the subscription in disconnectedCallback.
• Call this.adapter.valueChanged(newValue) to update the form data; call this.adapter.onBlur() from a @blur handler.
• Adding class="product-rating" and binding flex to templateData.size lets the input participate in flex parents — see Sizing custom widgets for the rationale.

product-rating.element.ts

import { html, LitElement, nothing } from 'lit';
import { customElement } from 'lit/decorators.js';
import { consume, provide } from '@lit/context';
import { Subscription } from 'rxjs';
import type { InputWidget, WithWidget } from '@golemui/core';
import {
  formContext,
  inputContext,
  InputWidgetAdapter,
  type LitFormContext,
} from '@golemui/lit';

interface ProductRatingProps {
  maxRating: number;
}

@customElement('app-product-rating')
export class ProductRatingElement
  extends LitElement
  implements WithWidget
{
  widget!: InputWidget<number>;

  @consume({ context: formContext })
  formContext!: LitFormContext<any>;

  @provide({ context: inputContext })
  adapter = new InputWidgetAdapter<number, ProductRatingProps>();

  subscriptions: Subscription[] = [];

  override createRenderRoot() {
    return this;
  }

  override connectedCallback() {
    super.connectedCallback();
    this.classList.add('product-rating');
    this.adapter.context = this.formContext;
    this.adapter.init(this.widget);

    this.subscriptions.push(
      this.adapter.templateDataChanged$.subscribe(() =>
        this.requestUpdate(),
      ),
    );
  }

  override render() {
    const { value, errors, touched, maxRating } =
      this.adapter.templateData;
    const stars = maxRating || 5;

    return html`
      <div class="product-rating__widget" id=${this.widget.uid}>
        <div
          class="product-rating__stars"
          tabindex="0"
          @blur=${() => this.adapter.onBlur()}
        >
          ${Array.from({ length: stars }, (_, i) => i + 1).map(
            (star) => html`
              <span
                role="button"
                class="product-rating__star ${star <= (value || 0)
                  ? 'product-rating__star--active'
                  : ''}"
                @click=${() => this.adapter.valueChanged(star)}
              >
                ${star <= (value || 0) ? '★' : '☆'}
              </span>
            `,
          )}
        </div>
        ${touched && errors?.length
          ? html`
              <div class="product-rating__errors">
                ${errors.map(
                  (error: string) =>
                    html`<span class="product-rating__error"
                      >${error}</span
                    >`,
                )}
              </div>
            `
          : nothing}
      </div>
    `;
  }

  override disconnectedCallback() {
    super.disconnectedCallback();
    this.adapter.destroy();
    this.subscriptions.forEach((s) => s.unsubscribe());
  }
}

Vue

Key concepts (Vue)

• useInputWidget returns reactive Refs for value, errors, isTouched, and templateData (your custom props + engine-managed values). Vue’s template auto-unwraps refs.
• Call onValueChanged(newValue) from a click handler — the engine writes through to the form data and runs validation.
• Call onBlur() when the user leaves the field. With validateOn: 'blur' (or 'eager'), this triggers validation; either way, it sets isTouched.
• :style="{ flex: templateData.size }" lets the input participate in flex parents — see Sizing custom widgets for the rationale.

ProductRating.vue

<script setup lang="ts">
import type { InputWidget, WithWidget } from '@golemui/core';
import { useInputWidget } from '@golemui/vue';
import { computed } from 'vue';

interface ProductRatingProps {
  maxRating: number;
}

const props = defineProps<WithWidget>();
const widget = props.widget as InputWidget<number>;
const { uid, value, errors, isTouched, templateData, onValueChanged, onBlur } =
  useInputWidget<number, ProductRatingProps>(widget);

const maxRating = computed(() => templateData.value.maxRating || 5);
const stars = computed(() => Array.from({ length: maxRating.value }, (_, i) => i + 1));
</script>

<template>
  <div class="product-rating" :style="{ flex: templateData.size }">
    <div class="product-rating__widget" :id="uid">
      <div class="product-rating__stars" tabindex="0" @blur="onBlur">
        <span
          v-for="star in stars"
          :key="star"
          role="button"
          :class="['product-rating__star', star <= (value || 0) && 'product-rating__star--active']"
          @click="onValueChanged(star)"
        >
          {{ star <= (value || 0) ? '★' : '☆' }}
        </span>
      </div>
      <div v-if="isTouched && errors.length > 0" class="product-rating__errors">
        <span v-for="(error, i) in errors" :key="i" class="product-rating__error">
          {{ error }}
        </span>
      </div>
    </div>
  </div>
</template>

Vanilla JS

Key concepts (Vanilla JS)

• Extend LitElement from lit (already a transitive dependency via @golemui/lit). Consume formContext and provide inputContext so any nested widget can resolve through the registry.
• Subscribe to adapter.templateDataChanged$ to drive requestUpdate(). Clean up the subscription in disconnectedCallback.
• Call this.adapter.valueChanged(newValue) to update the form data; call this.adapter.onBlur() from a @blur handler.
• Register the class with customElements.define('app-product-rating', ProductRatingElement) at the bottom of the file.
• Adding class="product-rating" and binding flex to templateData.size lets the input participate in flex parents — see Sizing custom widgets for the rationale.

product-rating.element.ts

import { html, LitElement, nothing } from 'lit';
import { consume, provide } from '@lit/context';
import { Subscription } from 'rxjs';
import type { InputWidget, WithWidget } from '@golemui/core';
import {
  formContext,
  inputContext,
  InputWidgetAdapter,
  type LitFormContext,
} from '@golemui/lit';

interface ProductRatingProps {
  maxRating: number;
}

export class ProductRatingElement
  extends LitElement
  implements WithWidget
{
  widget!: InputWidget<number>;

  @consume({ context: formContext })
  formContext!: LitFormContext<any>;

  @provide({ context: inputContext })
  adapter = new InputWidgetAdapter<number, ProductRatingProps>();

  subscriptions: Subscription[] = [];

  override createRenderRoot() {
    return this;
  }

  override connectedCallback() {
    super.connectedCallback();
    this.classList.add('product-rating');
    this.adapter.context = this.formContext;
    this.adapter.init(this.widget);

    this.subscriptions.push(
      this.adapter.templateDataChanged$.subscribe(() =>
        this.requestUpdate(),
      ),
    );
  }

  override render() {
    const { value, errors, touched, maxRating } =
      this.adapter.templateData;
    const stars = maxRating || 5;

    return html`
      <div class="product-rating__widget" id=${this.widget.uid}>
        <div
          class="product-rating__stars"
          tabindex="0"
          @blur=${() => this.adapter.onBlur()}
        >
          ${Array.from({ length: stars }, (_, i) => i + 1).map(
            (star) => html`
              <span
                role="button"
                class="product-rating__star ${star <= (value || 0)
                  ? 'product-rating__star--active'
                  : ''}"
                @click=${() => this.adapter.valueChanged(star)}
              >
                ${star <= (value || 0) ? '★' : '☆'}
              </span>
            `,
          )}
        </div>
        ${touched && errors?.length
          ? html`
              <div class="product-rating__errors">
                ${errors.map(
                  (error: string) =>
                    html`<span class="product-rating__error"
                      >${error}</span
                    >`,
                )}
              </div>
            `
          : nothing}
      </div>
    `;
  }

  override disconnectedCallback() {
    super.disconnectedCallback();
    this.adapter.destroy();
    this.subscriptions.forEach((s) => s.unsubscribe());
  }
}

customElements.define('app-product-rating', ProductRatingElement);

Result

Try clicking the stars to select a rating, then click away to trigger validation:

See also

• Custom Widgets Overview — the full Product Card example with all four kinds.
• Sizing custom widgets — why every widget reads templateData.size.
• Form Definition API / Custom Widgets — gui.inputs.custom(...) reference.
• Features / Validators — validators on custom inputs.