nuxt-x-app-formkit

FormKit-powered form containers for Nuxt 4. Provides three auto-imported XForm-prefixed components — a modal form, a slideover panel form, and a drag-and-drop file upload zone.

All form containers support two modes:

• CRUD mode — pass an endpoint prop and the component handles fetch, submit, validation, toast notifications, and close automatically
• Legacy mode — omit endpoint and handle submission yourself via the @submit event

What the consumer writes

The layer bundles all FormKit wiring — @formkit/nuxt, the FormKit config (genesis icons + the custom fileUpload input), and optional FormKit Pro auto-loading. The minimal consumer setup is:

npm install @xenterprises/nuxt-x-app-formkit

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'], // required peer (or extend @xenterprises/nuxt-x-app)
  extends: ['@xenterprises/nuxt-x-app-formkit']
})

Optional — FormKit Pro (requires @formkit/pro installed, see Prerequisites):

# .env — must start with fk-; read at BUILD time (changing it requires a rebuild)
FORMKIT=fk-your-pro-key-here

The layer ships no FormKit theme. Provide your own formkit.theme.ts and reference it from your own formkit.config.ts via rootClasses — see Configuration for the full theme setup (including the Tailwind v4 @source directive). No app/app.config.ts keys exist for this layer; all behavior is prop-driven.

Components

Quick Example

<template>
  <UButton @click="open = true">New User</UButton>

  <XFormModal
    v-model="open"
    endpoint="/api/users"
    on-success="refresh"
  >
    <FormKit type="text" name="name" label="Name" validation="required" />
    <FormKit type="email" name="email" label="Email" validation="required|email" />
  </XFormModal>
</template>

<script setup>
const open = ref(false)
</script>

Prerequisites

• nuxt ^4.0.0 (peer)
• @nuxt/ui ^4.0.0 (peer) — provides UModal, USlideover, useToast
• @formkit/pro >=0.127.24 <0.129.0 (optional peer) — install only if you use FormKit Pro. This range is the FormKit 1.x line: 0.128.0 is the last release compatible with the layer's @formkit/nuxt ^1.7.2; 0.129.0+ requires FormKit 2.x. With @formkit/pro installed and a FORMKIT=fk-... env var present at build time, the layer swaps to its bundled formkit.config.pro.ts and registers the Pro plugin.

Composables

Migration Notes

2026-07 — XFormModal / XFormSlide slot-hijack fix (v0.2.1)

@formkit/nuxt's auto-import build plugin (unplugin-formkit) injects a FormKitLazyProvider around the root element's children of any SFC using <FormKit>. With UModal / USlideover as the single root, the provider was injected inside the overlay and hijacked its internal #content slot — the modal/slideover rendered an empty shell and named slots were silently lost. Both components now wrap the overlay in a plain div so the provider lands outside it.

Action: consumers on 0.2.x builds published before 2026-07-23 should update to >=0.2.1. No API or markup change is required — named slots (#header, #footer, #loading, #error, default) work as documented once updated.

AI Context

package: "@xenterprises/nuxt-x-app-formkit"
prefix: XForm
components: [XFormModal, XFormSlide, XFormFileUpload]
peers: { nuxt: ^4.0.0, "@nuxt/ui": ^4.0.0, "@formkit/pro": ">=0.127.24 <0.129.0 (optional)" }
crud-mode: pass endpoint prop — component handles fetch/submit/toast/close
legacy-mode: omit endpoint — handle @submit yourself
env: FORMKIT=fk-... (optional FormKit Pro key)
use-when: Building forms that create or edit resources via API, with modal or slideover UX