nuxt-x-app-formkit
Modal
FormKit-powered modal form with automatic CRUD mode and legacy submit support.
Modal
XFormModal wraps a FormKit form inside a UModal. In CRUD mode (pass an endpoint prop) the component fetches an existing record by recordId, runs FormKit validation on submit, posts/puts to the API, shows a toast, and optionally refreshes or navigates on success. In legacy mode (omit endpoint) handle submission yourself via the @submit event.
Components
<XFormModal />
<!-- CRUD mode — create -->
<XFormModal v-model="open" endpoint="/api/users" on-success="refresh">
<FormKitText name="name" label="Name" validation="required" />
<FormKitText name="email" label="Email" validation="required|email" />
</XFormModal>
<!-- CRUD mode — edit -->
<XFormModal v-model="open" endpoint="/api/users" :record-id="user.id" on-success="refresh" />
<!-- Legacy mode -->
<XFormModal v-model="open" title="Custom Form" @submit="handleSubmit">
<input v-model="form.name" />
</XFormModal>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | boolean | false | Controls modal open state (v-model) |
title | string | "" | Modal header title. Auto-derived from endpoint when omitted |
size | "sm" | "md" | "lg" | "xl" | "full" | "md" | Max-width of the modal content |
closable | boolean | true | Show the X close button in the header |
loading | boolean | false | External loading state merged into button disabled/spinner |
disabled | boolean | false | Disable the submit button |
submitText | string | "Save" | Submit button label (auto becomes "Create" / "Update" in CRUD mode) |
cancelText | string | "Cancel" | Cancel button label |
confirmClose | boolean | false | Suppress auto-close on X click; handle @close yourself |
endpoint | string | — | API base path (e.g. /api/users). Enables CRUD mode |
recordId | string | number | — | ID of the record to fetch and edit |
initialData | Record<string, any> | — | Pre-populate form without fetching from API |
method | "POST" | "PUT" | "PATCH" | auto | HTTP method override (defaults to POST for create, PUT for edit) |
idKey | string | "id" | Key used to detect and append record ID to the URL |
headers | Record<string,string> | () => Record<string,string> | — | Extra request headers, or a function returning them |
transform | (data) => data | — | Transform form data before it is sent to the API |
showToast | boolean | true | Show success/error toasts via useToast() |
closeOnSuccess | boolean | true | Close modal after a successful API call |
resetOnClose | boolean | true | Clear form data when the modal closes |
formId | string | auto | Override the generated FormKit form node ID |
onSuccess | "refresh" | "navigate" | Function | — | Post-success action: refresh Nuxt data, navigate to a route, or custom callback |
navigateTo | string | — | Route template for onSuccess: "navigate" (supports :id / {id}) |
Emits
| Event | Payload | Description |
|---|---|---|
update:modelValue | boolean | v-model sync |
submit | — | Fired in legacy mode when the submit button is clicked |
close | — | Fired when the X or Cancel button is clicked |
success | (data, response) | Fired after a successful API call |
error | (error) | Fired when the API call fails |
loaded | (data) | Fired after the record is fetched by recordId |
Exposed Methods
| Method | Description |
|---|---|
open(data?) | Open the modal and optionally pre-populate form data |
close() | Close the modal |
reset() | Re-initialize form data |
submit() | Programmatically trigger form submission |
AI Context
component: XFormModal
package: "@xenterprises/nuxt-x-app-formkit"
crud-mode: pass endpoint prop; component handles fetch/submit/toast/close automatically
legacy-mode: omit endpoint; handle @submit event yourself
success-behaviors: onSuccess="refresh" | "navigate" | custom function
form-engine: FormKit (validation, node.submit(), node.setErrors())
ui-primitive: UModal (Nuxt UI)
use-when: Modal forms for creating or editing a resource via API