FormKit Nuxt UI

⚠️ Work in Progress: This project is under active development. APIs, components, and features may change without notice. While the core functionality is stable, expect breaking changes in minor versions until v1.0.0 is released. Use with caution in production environments.

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

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

• nuxtUICheckbox - Single checkbox with label and description
• nuxtUICheckboxGroup - Multiple checkbox selection
• nuxtUIColorPicker - Color selection with multiple formats
• 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
• nuxtUIInputTags - Tag input with custom delimiters
• nuxtUIInputTime - Time picker with 12/24-hour format
• 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

📊 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

🔧 Composables - Reusable form logic

• useFormKitInput - Input component utilities
• useFormKitOutput - Output component utilities
• useFormKitRepeater - Repeatable form sections
• useFormKitSchema - Schema-based form generation

🎨 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

• Checkbox
• CheckboxGroup
• ColorPicker
• Input
• InputDate
• InputMenu
• InputNumber
• InputTags
• InputTime
• PinInput
• RadioGroup
• Select
• SelectMenu
• Slider
• Switch
• Textarea

Output Components

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

Development

Local development setup

# 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
• Vue 3.x
• @nuxt/ui 4.3.0+
• @formkit/vue 1.x
• @formkit/nuxt 1.x

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,
  nuxtUISelectDefinition 
} from '@sfxcode/nuxt-ui-formkit/definitions'

export default defineFormKitConfig({
  inputs: {
    nuxtUICheckbox: nuxtUICheckboxDefinition,
    nuxtUIInput: nuxtUIInputDefinition,
    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