GkForm

Renders a native <form> with novalidate, wires submit to async validation, and exposes headless state from createForm via the default slot. Does not register child fields like Vuetify; pair with GkField and app-level validation.

When to use

Use GkForm when you want native form semantics plus async validation state exposed through slot props. Keep field rendering explicit with GkField and control primitives so apps can choose their own validation strategy.

Live Examples

Async validation

Pass validate on GkForm; use isValidating for submit button loading.

Email

vue

<script setup lang="ts">
import { GkButton, GkField, GkForm, GkInput } from 'god-kit/vue'
import type { SubmitEventPromise } from 'god-kit/vue'
import { ref } from 'vue'

const email = ref('')
const last = ref('')

/** Simulates async validation so `isValidating` / submit loading stay on for ~1s */
async function demoValidate() {
  await new Promise<void>((r) => setTimeout(r, 1000))
  return { valid: true, errors: [] }
}

function onSubmit(e: SubmitEventPromise) {
  e.then((r) => {
    last.value = r.valid ? `ok: ${email.value}` : 'invalid'
  })
}
</script>

<template>
  <GkForm :validate="demoValidate" @submit="onSubmit">
    <template #default="{ isValidating, validate }">
      <GkField label="Email">
        <GkInput
          v-model="email"
          type="email"
          autocomplete="email"
          placeholder="you@example.com"
        />
      </GkField>
      <div class="gk-doc-row">
        <GkButton
          type="button"
          variant="secondary"
          @click="validate"
        >
          Validate
        </GkButton>

        <GkButton
          type="submit"
          variant="primary"
          :loading="isValidating"
        >
          Submit test
        </GkButton>
      </div>
      <p v-if="last" class="gk-doc-muted">
        {{ last }}
      </p>
    </template>
  </GkForm>
</template>

<style scoped>
.gk-doc-row {
  display: flex;
  flex-wrap: wrap;
  margin-top: var(--gk-space-2);
  gap: var(--gk-space-2);
}

.gk-doc-muted {
  margin: 0;
  font-size: var(--gk-font-size-sm);
  color: var(--gk-color-on-surface-muted);
}
</style>

Best practice: Handle SubmitEventPromise in submit listeners so you react after validation finishes.

Disabled & readonly

Toggle form-level disabled and readonly; slot exposes isDisabled and isReadonly.

Disabled Readonly

Form flags → disabled: false, readonly: false

vue

<script setup lang="ts">
import { GkForm } from 'god-kit/vue'
import { ref } from 'vue'

const disabledMode = ref(false)
const readonlyMode = ref(false)
</script>

<template>
  <div class="gk-doc-stack">
    <div class="gk-doc-row">
      <label><input v-model="disabledMode" type="checkbox"> Disabled</label>
      <label><input v-model="readonlyMode" type="checkbox"> Readonly</label>
    </div>
    <GkForm :disabled="disabledMode" :readonly="readonlyMode">
      <template #default="{ isDisabled, isReadonly }">
        <p class="gk-doc-muted">
          Form flags → disabled: {{ isDisabled }}, readonly: {{ isReadonly }}
        </p>
      </template>
    </GkForm>
  </div>
</template>

<style scoped>
.gk-doc-stack {
  display: flex;
  flex-direction: column;
  gap: var(--gk-space-3);
  max-width: 22rem;
}

.gk-doc-row {
  display: flex;
  flex-wrap: wrap;
  gap: var(--gk-space-3);
  font-size: var(--gk-font-size-sm);
}

.gk-doc-muted {
  margin: 0;
  font-size: var(--gk-font-size-sm);
  color: var(--gk-color-on-surface-muted);
}
</style>

API

Props

Prop	Type	Default	Description
controlSize	'xs' | 'sm' | 'md' | 'lg' | 'xl'	—	Default visual scale for GkInput, GkSelect, GkTextarea, GkCheckbox, and GkRadio inside this form via GK_FORM_CONTROLS. Omitted: inherits from a parent GkFormControlsProvider or createGkKit({ form: { defaultControlSize } }), else md.
disabled	boolean	false	Exposed on slot (future: provide to children)
readonly	boolean	false	Exposed on slot
validate	() => FormValidationResult | Promise<FormValidationResult>	—	Optional custom validation (e.g. async API). While it runs, slot isValidating is true. Omit for default createForm behavior (errors ref only).

Events

Event	Payload	Description
submit	SubmitEventPromise	Fired on submit; the event is extended with then / catch / finally bound to the validation Promise (Vuetify-style). Default action is preventDefault. If the listener does not call preventDefault, and validation resolves valid: true, HTMLFormElement.submit() is called (no second submit event).

Default slot (scoped)

Prop	Type	Description
errors	FieldValidationResult[]	Collected errors (empty until you wire createForm with custom validate)
isDisabled	boolean	From props
isReadonly	boolean	From props
isValidating	boolean	While validate() runs
isValid	boolean | null	Last validation outcome
items	FormField[]	Reserved (currently [])
validate	() => Promise<FormValidationResult>	Run validation
reset	() => void	Clears validation state (native reset is handled by the browser reset button)
resetValidation	() => void	Clears errors only

Headless createForm

Use createForm from god-kit/vue (or vue/form) when you need the same state object without GkForm:

import { createForm } from 'god-kit/vue'

const form = createForm({
  disabled: () => false,
  readonly: () => false,
  async validate() {
    return { valid: true, errors: [] }
  },
})

Examples

Each scenario under Live Examples includes a copyable Vue snippet.

For SubmitEventPromise, handle async results on the event (for example e.then((result) => { … })) so you run code after validation finishes.

Accessibility notes

• Prefer real submit controls (type="submit") so Enter-to-submit works naturally.
• Keep labels and error semantics in GkField; GkForm coordinates validation flow, not field accessibility markup.
• If async validation blocks submission, ensure busy state is visible on submit actions.

Related

• Form control size — defaults and GK_FORM_CONTROLS
• GkField
• GkInput
• GkSelect