@sfxcode/nuxt-ui-formkit

Nuxt UI FormKit

Seamless integration between FormKit form handling and Nuxt UI components for Nuxt 4

FormKit Nuxt UI bridges the gap between FormKit's powerful form management and Nuxt UI's beautiful component library, providing a complete solution for building forms in Nuxt applications.

• ✨  Release Notes
• 🏀  Live Playground
• 📖  FormKit Documentation
• 🎨  Nuxt UI Documentation

Features

✨ 22 Input Components - Complete set of FormKit-wrapped Nuxt UI input components

• nuxtUICalendar - Bare date-grid picker with range/multiple selection
• nuxtUICheckbox - Single checkbox with label and description
• nuxtUICheckboxGroup - Multiple checkbox selection
• nuxtUIColorPicker - Color selection with multiple formats
• nuxtUIEditor - Tiptap-based rich text editor
• nuxtUIFileUpload - Drag/drop and click-to-browse file input
• nuxtUIInput - Text input with various types (text, email, password, etc.)
• nuxtUIInputDate - Date and time picker with range support
• nuxtUIInputMenu - Dropdown menu with searchable options
• nuxtUIInputNumber - Number input with increment/decrement buttons
• nuxtUIInputRating - Star-based rating input for numeric values
• nuxtUIInputTags - Tag input with custom delimiters
• nuxtUIInputTime - Time picker with 12/24-hour format
• nuxtUIListbox - Listbox for single/multiple selection with filtering (for use with transfer mode lucide icons must be installed additionally)
• nuxtUIPinInput - PIN/OTP entry component
• nuxtUIRadioGroup - Radio button group for single selection
• nuxtUISelect - Select dropdown with search
• nuxtUISelectMenu - Advanced select with grouping
• nuxtUISlider - Range slider for numeric values
• nuxtUISwitch - Toggle switch for boolean states
• nuxtUITextarea - Multi-line text input with autoresize
• nuxtUITree - Hierarchical selection input (categories, org charts, file trees)

🔁 Repeater Component - Dynamic repeatable form sections

• nuxtUIRepeater - Create dynamic lists with add, remove, clone, and reorder functionality

🧭 Multi-Step Forms - Wizard-style forms with tab navigation and validation gating

• nuxtUIMultiStep - Tab-strip wizard container built on @formkit/addons' createMultiStepPlugin
• nuxtUIStep - A single step's content, with Nuxt UI-styled previous/next actions

📊 6 Output Components - Display-only components for read-only data

• nuxtUIOutputBoolean - Boolean display with custom icons
• nuxtUIOutputDate - Formatted date/time display
• nuxtUIOutputLink - URL display with navigation
• nuxtUIOutputList - List display with separators and badge styles
• nuxtUIOutputNumber - Formatted number display (currency, percentage)
• nuxtUIOutputText - Styled text display with icons

🎯 Form Management - Powerful form utilities

• FUDataEdit - Edit forms with schema-based configuration
• FUDataView - Read-only data display with schema support
• FUDataDebug - Development tool for form debugging
• FUAutoForm - Schema-free forms: inputs inferred from your data's value shapes, or a Valibot/Zod schema, with an override map for fine-tuning

🛡️ Standard Schema Validation - Validate against Zod/Valibot/ArkType instead of hand-written validation strings

• FUDataEdit's standardSchema prop, or useFormKitForm's standardSchema option - errors land on the exact field (including inside a repeater row), respecting each field's own validation-visibility timing

⚙️ Config Helper - One-line formkit.config.ts setup

• createNuxtUiFormkitConfig - Assembles all nuxtUIXxx inputs/outputs and this module's plugins into { inputs, plugins } you spread into your own config

🔧 Composables & Utilities - Reusable form logic

• useFormKitSchema - Schema-based form generation with element builders
• useFormKitInput - Input component utilities and prop handling
• useFormKitOutput - Output component utilities and prop handling
• useFormKitRepeater - Repeater insert/remove/clone/move/drag handlers
• useFormKitMultiStep - Multi-step tab-item mapping and navigation bridging
• useFormKitForm - Submit/reset/error-management wrapper for a form's imperative APIs, callable from outside the form
• useFormKitAutoForm - Schema inference from data value shapes, Valibot, or Zod schemas (inferFormSchema/inferFormSchemaFromValibot/inferFormSchemaFromZod)
• useFormKitOverlay - Promise-based modal/slideover forms: await overlay.edit({ data, schema, title }) (or .auto(...) for a schema-free version), resolving to the saved data or null on cancel
• colorConverter - Color format conversion utilities
• durationConverter - Duration format conversion utilities

🎨 Full Nuxt UI Integration - All components respect Nuxt UI theming

• Color modes (light/dark)
• Design tokens
• Accessibility features
• Responsive design

✅ TypeScript Support - Full type safety with IntelliSense ⚡ SSR Compatible - Works seamlessly with Nuxt's server-side rendering 🔄 Auto-imports - Components and composables auto-imported 📝 Validation - Built-in FormKit validation support

Quick Setup

Install the module to your Nuxt application:

# Using pnpm (recommended)
pnpm add @sfxcode/nuxt-ui-formkit

# Using npm
npm install @sfxcode/nuxt-ui-formkit

# Using yarn
yarn add @sfxcode/nuxt-ui-formkit

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    '@nuxt/ui',
    '@sfxcode/nuxt-ui-formkit'
  ]
})

That's it! You can now use FormKit Nuxt UI components in your Nuxt app ✨

Usage

Basic Form Example

<template>
  <FormKit
    type="form"
    @submit="handleSubmit"
  >
    <FormKit
      type="nuxtUIInput"
      name="email"
      label="Email Address"
      placeholder="your.email@example.com"
      validation="required|email"
    />

    <FormKit
      type="nuxtUIInput"
      name="password"
      input-type="password"
      label="Password"
      validation="required|length:8"
    />

    <FormKit
      type="nuxtUICheckbox"
      name="terms"
      label="I agree to the terms and conditions"
      validation="accepted"
    />

    <UButton type="submit">
      Sign Up
    </UButton>
  </FormKit>
</template>

<script setup lang="ts">
const handleSubmit = (data: any) => {
  console.log('Form submitted:', data)
}
</script>

Schema-Based Form

<template>
  <FUDataEdit
    :data="formData"
    :schema="userSchema"
    @submit="handleSubmit"
  />
</template>

<script setup lang="ts">
const formData = ref({
  name: '',
  email: '',
  age: 0,
  subscribe: false
})

const userSchema = [
  {
    $formkit: 'nuxtUIInput',
    name: 'name',
    label: 'Full Name',
    validation: 'required'
  },
  {
    $formkit: 'nuxtUIInput',
    name: 'email',
    inputType: 'email',
    label: 'Email',
    validation: 'required|email'
  },
  {
    $formkit: 'nuxtUIInputNumber',
    name: 'age',
    label: 'Age',
    min: 0,
    max: 120
  },
  {
    $formkit: 'nuxtUISwitch',
    name: 'subscribe',
    label: 'Subscribe to newsletter'
  }
]

const handleSubmit = (data: any) => {
  console.log('Form submitted:', data)
}
</script>

Advanced Number Input with Formatting

<FormKit
  type="nuxtUIInputNumber"
  name="price"
  label="Product Price"
  :min="0"
  :step="0.01"
  :format-options="{
    style: 'currency',
    currency: 'USD'
  }"
  validation="required|min:0"
/>

Output Components for Display

<template>
  <FUDataView
    :data="userData"
    :schema="displaySchema"
  />
</template>

<script setup lang="ts">
const userData = ref({
  name: 'John Doe',
  email: 'john@example.com',
  price: 1234.56,
  tags: ['Vue', 'Nuxt', 'TypeScript'],
  isActive: true
})

const displaySchema = [
  {
    $formkit: 'nuxtUIOutputText',
    name: 'name',
    label: 'Name',
    leadingIcon: 'i-heroicons-user'
  },
  {
    $formkit: 'nuxtUIOutputLink',
    name: 'email',
    label: 'Email',
    leadingIcon: 'i-heroicons-envelope'
  },
  {
    $formkit: 'nuxtUIOutputNumber',
    name: 'price',
    label: 'Price',
    formatOptions: {
      style: 'currency',
      currency: 'USD'
    }
  },
  {
    $formkit: 'nuxtUIOutputList',
    name: 'tags',
    label: 'Technologies',
    listType: 'badge',
    color: 'primary'
  },
  {
    $formkit: 'nuxtUIOutputBoolean',
    name: 'isActive',
    label: 'Status',
    trueValue: 'Active',
    falseValue: 'Inactive'
  }
]
</script>

Component Props

All components support their respective Nuxt UI component props plus FormKit-specific props like name, label, help, validation, etc.

Refer to the Nuxt UI documentation for component-specific props and the FormKit documentation for validation and form handling.

Examples

The playground includes comprehensive examples for all components:

Input Components

• Calendar
• Checkbox
• CheckboxGroup
• ColorPicker
• Editor
• FileUpload
• Input
• InputDate
• InputMenu
• InputNumber
• InputRating
• InputTags
• InputTime
• Listbox
• PinInput
• RadioGroup
• Select
• SelectMenu
• Slider
• Switch
• Textarea

Output Components

• OutputBoolean
• OutputDate
• OutputLink
• OutputList
• OutputNumber
• OutputText

Repeater

• Repeater
• Drag-and-Drop Repeater

Multi-Step

• Multi-Step Form

Form Composable

• useFormKitForm

Standard Schema Validation

• Standard Schema Validation

Development

# Clone the repository
git clone https://github.com/sfxcode/nuxt-ui-formkit.git
cd nuxt-ui-formkit

# Install dependencies (using pnpm)
pnpm install

# Generate type stubs
pnpm dev:prepare

# Start development server with playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run tests
pnpm test
pnpm test:watch

# Build the module
pnpm build

# Release new version
pnpm release

Requirements

• Nuxt 4.x (>=4.0.0)
• Vue 3.5+
• @nuxt/ui 4.12+ (some features need newer releases: PinInput slot types 4.9+, ProgressGroup 4.11+)
• @formkit/nuxt 2.x, added to your modules (this module does not install it for you - see Installation)

See Known limitations for behaviors worth knowing before you build on it.

External Module Usage

External Nuxt modules and applications can import FormKit definitions programmatically.

Import All Definitions

import { nuxtUIInputs, nuxtUIOutputs } from '@sfxcode/nuxt-ui-formkit/formkit'

// Use in FormKit config
export default defineFormKitConfig({
  inputs: {
    ...nuxtUIInputs,
    ...nuxtUIOutputs,
  },
})

Import Individual Definitions

import { 
  nuxtUICheckboxDefinition,
  nuxtUIInputDefinition,
  nuxtUIListboxDefinition,
  nuxtUISelectDefinition 
} from '@sfxcode/nuxt-ui-formkit/definitions'

export default defineFormKitConfig({
  inputs: {
    nuxtUICheckbox: nuxtUICheckboxDefinition,
    nuxtUIInput: nuxtUIInputDefinition,
    nuxtUIListbox: nuxtUIListboxDefinition,
    nuxtUISelect: nuxtUISelectDefinition,
  },
})

Available Import Paths

• @sfxcode/nuxt-ui-formkit/formkit - All definitions + type augmentation
• @sfxcode/nuxt-ui-formkit/definitions - Definition objects only

For detailed usage examples, see EXTERNAL_USAGE.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using Conventional Commits (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License © 2024-present sfxcode

Credits

• FormKit - Form framework for Vue
• Nuxt UI - UI library for Nuxt
• Nuxt - The Intuitive Vue Framework