GkField

Wraps a single form control: label (optional), default slot for GkInput (or future controls), an optional hint, and an error string with role="alert".

When to use

Use for every labeled control in a form so ids, aria-describedby, and error text stay consistent.

Live Examples

Basic

Submit runs simple validation and sets the field error string.

Email

vue

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

const email = ref('')
const err = ref('')

function validate() {
  err.value = email.value.includes('@') ? '' : 'Enter a valid email.'
}
</script>

<template>
  <form class="gk-doc-form" @submit.prevent="validate">
    <GkField label="Email" :error="err">
      <GkInput v-model="email" type="email" autocomplete="email" />
    </GkField>
    <GkButton type="submit" variant="primary">
      Validate
    </GkButton>
  </form>
</template>

<style scoped>
.gk-doc-form {
  display: flex;
  flex-direction: column;
  gap: var(--gk-space-4);
  max-width: 20rem;
}
</style>

Best practice: Keep one control per GkField so label and aria-describedby stay unambiguous.

Static error

Pass :error from your validation layer to show invalid state and the alert region.

Email

Use an address with @.

vue

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

const email = ref('not-an-email')
const emailError = ref('Use an address with @.')
</script>

<template>
  <GkField label="Email" :error="emailError">
    <GkInput v-model="email" type="email" autocomplete="email" />
  </GkField>
</template>

Visually hidden label

label-sr-only keeps a proper label for assistive tech when the visible heading lives elsewhere.

API key

vue

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

const apiKey = ref('')
const apiKeyError = ref('')
</script>

<template>
  <GkField label="API key" label-sr-only :error="apiKeyError || undefined">
    <GkInput v-model="apiKey" aria-label="API key" placeholder="sk-…" />
  </GkField>
</template>

API

Props

Prop	Type	Default	Description
label	string	—	Visible label text
error	string	—	Error message; sets invalid state on child input
hint	string	—	Helper text under the control; hidden while error is set
labelSrOnly	boolean	false	Visually hide label but keep for screen readers

Slots

Slot	Description
default	The input or control (e.g. GkInput)

Provide / inject

GkField uses useFieldIds() internally, then provides context for child controls (inputId, errorId, errorMessage, hintId, hintMessage). See Composables for headless usage without GkField. You rarely need to use the injection key directly; import GK_FIELD from god-kit/vue only for advanced cases.

Hint and error

<GkField label="Email" hint="We never share it.">
  <GkInput v-model="email" type="email" />
</GkField>

An error replaces the hint rather than stacking with it, so the control's aria-describedby always points at exactly one message and screen readers announce the error instead of stale help text.

Examples

Each scenario under Live Examples includes a copyable Vue snippet.

Accessibility notes

• Keep one control per field wrapper so label/id relationships remain clear.
• hint and error are mutually exclusive by design: only one is rendered, and it is the one aria-describedby references.
• Use labelSrOnly only when visible label text exists elsewhere in nearby UI context.

Related components

• GkInput
• GkTextarea
• GkSelect