Form Events

Widgets emit named events through the formEvent callback you pass to <gui-form> (or the @form-event emit in Vue). The form definition wires the widget event (a click, a value change, a load) to a name; your application matches on that name and reacts.

The event name is just a string you pick — your application listens for it. The form definition declares the wiring inline on the widget, identically in both paths.

Wiring events on widgets

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

const formDef = [
  gui.inputs.dropdown('country', {
    onChange: 'countryChanged',
    items: ['US', 'CA', 'MX'],
  }),
  gui.actions.button({ actionType: 'submit', label: 'Submit' }),
];

{
  "form": [
    {
      "kind": "input",
      "type": "dropdown",
      "path": "country",
      "items": ["US", "CA", "MX"],
      "on": { "change": "countryChanged" }
    },
    {
      "kind": "action",
      "type": "button",
      "label": "Submit",
      "actionType": "submit"
    }
  ]
}

Handling events in your component

formEvent is a callback prop in React, an output in Angular, a CustomEvent in Lit, an emitted event (@form-event) in Vue, and a CustomEvent you subscribe to via addEventListener in vanilla JS. Match on event.name and read event.data:

React

import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import { gui } from '@golemui/gui-shared';
import { GuiForm } from '@golemui/gui-react';

const formDef = [
  gui.inputs.dropdown('country', { onChange: 'countryChanged', items: ['US', 'CA', 'MX'] }),
  gui.actions.button({ actionType: 'submit', label: 'Submit' }),
];

function handleFormEvent(event: FormEvent) {
  if (event.name === 'countryChanged') {
    console.log('Country selected:', event.data.country);
  }
}

function handleFormSubmit(event: FormSubmitEvent) {
  console.log('Submitting:', event.data);
}

export function MyForm() {
  return (
    <GuiForm
      config={{ formDef }}
      formEvent={handleFormEvent}
      formSubmit={handleFormSubmit}
    />
  );
}

Angular

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import { gui } from '@golemui/gui-shared';
import { FormComponent } from '@golemui/gui-angular';

@Component({
  imports: [CommonModule, FormComponent],
  selector: 'app-my-form',
  template: `
    <gui-form
      [config]="config"
      (formEvent)="onFormEvent($event)"
      (formSubmit)="onFormSubmit($event)"
    ></gui-form>
  `,
})
export class MyForm {
  protected config = {
    formDef: [
      gui.inputs.dropdown('country', { onChange: 'countryChanged', items: ['US', 'CA', 'MX'] }),
      gui.actions.button({ actionType: 'submit', label: 'Submit' }),
    ],
  };

  protected onFormEvent(event: FormEvent) {
    if (event.name === 'countryChanged') {
      console.log('Country selected:', event.data.country);
    }
  }

  protected onFormSubmit(event: FormSubmitEvent) {
    console.log('Submitting:', event.data);
  }
}

Lit

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import { gui } from '@golemui/gui-shared';
import '@golemui/gui-lit';

@customElement('my-form')
export class MyForm extends LitElement {
  config = {
    formDef: [
      gui.inputs.dropdown('country', { onChange: 'countryChanged', items: ['US', 'CA', 'MX'] }),
      gui.actions.button({ actionType: 'submit', label: 'Submit' }),
    ],
  };

  override createRenderRoot() { return this; }

  protected onFormEvent(event: FormEvent) {
    if (event.name === 'countryChanged') {
      console.log('Country selected:', event.data.country);
    }
  }

  protected onFormSubmit(event: FormSubmitEvent) {
    console.log('Submitting:', event.data);
  }

  override render() {
    return html`
      <gui-form
        .config=${this.config}
        @formEvent=${(e: CustomEvent<FormEvent>) => this.onFormEvent(e.detail)}
        @formSubmit=${(e: CustomEvent<FormSubmitEvent>) => this.onFormSubmit(e.detail)}
      ></gui-form>
    `;
  }
}

Vue

<script setup lang="ts">
import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import { gui } from '@golemui/gui-shared';
import { GuiForm } from '@golemui/gui-vue';

const config = {
  formDef: [
    gui.inputs.dropdown('country', { onChange: 'countryChanged', items: ['US', 'CA', 'MX'] }),
    gui.actions.button({ actionType: 'submit', label: 'Submit' }),
  ],
};

function onFormEvent(event: FormEvent) {
  if (event.name === 'countryChanged') {
    console.log('Country selected:', event.data.country);
  }
}

function onFormSubmit(event: FormSubmitEvent) {
  console.log('Submitting:', event.data);
}
</script>

<template>
  <GuiForm
    :config="config"
    @form-event="onFormEvent"
    @form-submit="onFormSubmit"
  />
</template>

Vanilla JS

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

const config = {
  formDef: [
    gui.inputs.dropdown('country', { onChange: 'countryChanged', items: ['US', 'CA', 'MX'] }),
    gui.actions.button({ actionType: 'submit', label: 'Submit' }),
  ],
};

function onFormEvent(event) {
  if (event.name === 'countryChanged') {
    console.log('Country selected:', event.data.country);
  }
}

function onFormSubmit(event) {
  console.log('Submitting:', event.data);
}

const form = document.getElementById('app-form');
form.config = config;
form.addEventListener('formEvent', (e) => onFormEvent(e.detail));
form.addEventListener('formSubmit', (e) => onFormSubmit(e.detail));

React

import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import { GuiForm } from '@golemui/gui-react';
import formDef from './my-form.json';

function handleFormEvent(event: FormEvent) {
  if (event.name === 'countryChanged') {
    console.log('Country selected:', event.data.country);
  }
}

function handleFormSubmit(event: FormSubmitEvent) {
  console.log('Submitting:', event.data);
}

export function MyForm() {
  return (
    <GuiForm
      config={{ formDef }}
      formEvent={handleFormEvent}
      formSubmit={handleFormSubmit}
    />
  );
}

Angular

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import { FormComponent } from '@golemui/gui-angular';
import formDef from './my-form.json';

@Component({
  imports: [CommonModule, FormComponent],
  selector: 'app-my-form',
  template: `
    <gui-form
      [config]="config"
      (formEvent)="onFormEvent($event)"
      (formSubmit)="onFormSubmit($event)"
    ></gui-form>
  `,
})
export class MyForm {
  protected config = { formDef };

  protected onFormEvent(event: FormEvent) {
    if (event.name === 'countryChanged') {
      console.log('Country selected:', event.data.country);
    }
  }

  protected onFormSubmit(event: FormSubmitEvent) {
    console.log('Submitting:', event.data);
  }
}

Lit

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import type { FormEvent, FormSubmitEvent } from '@golemui/core';
import '@golemui/gui-lit';
import formDef from './my-form.json';

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

  override createRenderRoot() { return this; }

  protected onFormEvent(event: FormEvent) {
    if (event.name === 'countryChanged') {
      console.log('Country selected:', event.data.country);
    }
  }

  protected onFormSubmit(event: FormSubmitEvent) {
    console.log('Submitting:', event.data);
  }

  override render() {
    return html`
      <gui-form
        .config=${this.config}
        @formEvent=${(e: CustomEvent<FormEvent>) => this.onFormEvent(e.detail)}
        @formSubmit=${(e: CustomEvent<FormSubmitEvent>) => this.onFormSubmit(e.detail)}
      ></gui-form>
    `;
  }
}

Vue

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

const config = { formDef };

function onFormEvent(event: FormEvent) {
  if (event.name === 'countryChanged') {
    console.log('Country selected:', event.data.country);
  }
}

function onFormSubmit(event: FormSubmitEvent) {
  console.log('Submitting:', event.data);
}
</script>

<template>
  <GuiForm
    :config="config"
    @form-event="onFormEvent"
    @form-submit="onFormSubmit"
  />
</template>

Vanilla JS

import '@golemui/gui-components/index.css';
import '@golemui/gui-lit';
import formDef from './my-form.json';

const config = { formDef };

function onFormEvent(event) {
  if (event.name === 'countryChanged') {
    console.log('Country selected:', event.data.country);
  }
}

function onFormSubmit(event) {
  console.log('Submitting:', event.data);
}

const form = document.getElementById('app-form');
form.config = config;
form.addEventListener('formEvent', (e) => onFormEvent(e.detail));
form.addEventListener('formSubmit', (e) => onFormSubmit(e.detail));

Event types

Event	Emitted by
onClick	Action widgets (button, custom action).
onChange	Input widgets when their value changes.
onLoad	Dropdowns and lists during initialization.
onFilter	Dropdowns when the user types a search query.
onBlur	Input widgets when focus leaves.

In the JSON path, the same events live under the widget’s "on" block: "on": { "click": "...", "change": "...", "load": "...", "filter": "...", "blur": "..." }.

Event payload

The formEvent callback receives an object with:

• name — the string you wired in the form definition.
• data — the current form data at the moment the event fired.
• detail — optional payload supplied by the widget (e.g. the network id from a custom share button).

Note

Submit buttons (actionType: 'submit') go through the separate formSubmit event after form-level validation passes — they don’t surface in formEvent. That’s why the example above wires both callbacks.

See also

• Extending GolemUI / Widgets / Sending events — emitting events from your custom widgets.
• Form Definition API / Events — every event property accepted by the DX shortcuts.