Include & Exclude

Use include to render a widget only when one or more named states are active; use exclude to render it only when they are not active.

Both shapes accept either a list of state names ({ in: [...] }) or a one-off reactive expression ({ when: '...' }).

A complete include example

A boolean toggle reveals a discount-code input only when the user opts in. The state expression reads $form.hasDiscountCode and the discount input declares include: { in: ['hasDiscount'] }.

Programmatic

The state lives in formConfig.states; the include rule sits next to the widget’s other props.

React

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

const config = {
  formDef: [
    gui.inputs.booleanInput('hasDiscountCode', { label: 'I have a discount code' }),
    gui.inputs.textInput('discountCode', {
      label: 'Discount code',
      include: { in: ['hasDiscount'] },
    }),
  ],
  formConfig: {
    states: { hasDiscount: '$form.hasDiscountCode === true' },
  },
};

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

Angular

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
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"></gui-form>`,
})
export class MyForm {
  protected config = {
    formDef: [
      gui.inputs.booleanInput('hasDiscountCode', { label: 'I have a discount code' }),
      gui.inputs.textInput('discountCode', {
        label: 'Discount code',
        include: { in: ['hasDiscount'] },
      }),
    ],
    formConfig: {
      states: { hasDiscount: '$form.hasDiscountCode === true' },
    },
  };
}

Lit

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

@customElement('my-form')
export class MyForm extends LitElement {
  config = {
    formDef: [
      gui.inputs.booleanInput('hasDiscountCode', { label: 'I have a discount code' }),
      gui.inputs.textInput('discountCode', {
        label: 'Discount code',
        include: { in: ['hasDiscount'] },
      }),
    ],
    formConfig: {
      states: { hasDiscount: '$form.hasDiscountCode === true' },
    },
  };

  override createRenderRoot() { return this; }

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

Vue

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

const config = {
  formDef: [
    gui.inputs.booleanInput('hasDiscountCode', { label: 'I have a discount code' }),
    gui.inputs.textInput('discountCode', {
      label: 'Discount code',
      include: { in: ['hasDiscount'] },
    }),
  ],
  formConfig: {
    states: { hasDiscount: '$form.hasDiscountCode === true' },
  },
};
</script>

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

Vanilla JS

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

const form = document.getElementById('app-form');
form.config = {
  formDef: [
    gui.inputs.booleanInput('hasDiscountCode', { label: 'I have a discount code' }),
    gui.inputs.textInput('discountCode', {
      label: 'Discount code',
      include: { in: ['hasDiscount'] },
    }),
  ],
  formConfig: {
    states: { hasDiscount: '$form.hasDiscountCode === true' },
  },
};

JSON

The state lives at the form root under "states"; the widget carries "include" inline.

{
  "states": {
    "hasDiscount": "$form.hasDiscountCode === true"
  },
  "form": [
    {
      "kind": "input",
      "type": "checkbox",
      "path": "hasDiscountCode",
      "label": "I have a discount code"
    },
    {
      "kind": "input",
      "type": "textinput",
      "path": "discountCode",
      "label": "Discount code",
      "include": { "in": ["hasDiscount"] }
    }
  ]
}

Wire the parsed JSON into your form component the same way as any other JSON formDef:

React

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

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

Angular

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
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"></gui-form>`,
})
export class MyForm {
  protected config = { formDef };
}

Lit

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

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

  override createRenderRoot() { return this; }

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

Vue

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

const config = { formDef };
</script>

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

Vanilla JS

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

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

When $form.hasDiscountCode flips to true, the discount-code input mounts; flipping it back unmounts the widget and clears its data.

Active-state lists vs reactive when

Both include and exclude accept either form. Pick the one that reads best at the call site.

Programmatic

include: { in: ['hasDiscount'] }       // active-state list — name defined in formConfig.states
include: { when: '$form.age >= 18' }   // ad-hoc expression — no name needed

JSON

"include": { "in": ["hasDiscount"] }
"include": { "when": "$form.age >= 18" }

Use a named state when the same condition appears in multiple places. Use when for one-shot conditions (see Inline when).

Excluding a widget

exclude is the mirror of include — render the widget unless the state(s) match.

Programmatic

gui.displays.alert('signin-hint', {
  text: 'Already have an account? Sign in.',
  exclude: { from: ['hasAccount'] },
});

JSON

{
  "kind": "display",
  "type": "alert",
  "props": { "text": "Already have an account? Sign in." },
  "exclude": { "from": ["hasAccount"] }
}

See also

• States overview — declaring states in each path.
• Form Definition API / States — full include / exclude reference.