Arkform

A lightweight, TypeScript-first form library built for Vue and Arktype validation. Arkform provides strongly-typed forms with reactive state management, validation, and seamless component integration.

Overview

Arkform consists of two main composables that work together:

• $form - Form-level state management, validation, and submission handling
• $field - Individual input field management with automatic form integration

Key Features

• Type-safe validation using Arktype schemas
• Reactive state management with Nuxt's useState
• Automatic form/field binding via Vue's provide/inject
• Built-in loading states and error handling
• Theme system with SCSS support
• SSR compatible with hydration support

Quick Start

1. Define Your Form Schema

import { type as arktype } from "arktype"

const loginSchema = arktype({
  email: "string.email",
  password: "string"
})

export const forms = {
  login: { schema: loginSchema }
}

2. Create a Form

<template>
  <arkform name="login" theme="default" :submit="handleSubmit">
    <field name="email" placeholder="Enter your email" />
    <field name="password" type="password" />
    <button type="submit">Login</button>
  </arkform>
</template>

<script setup>
import { defineArkform } from "#arkform"

const { $form, $field } = defineArkform(forms)
const form = $form("login")

const handleSubmit = form.handleSubmit(async (result) => {
  if (!result.ok) {
    console.log("Validation errors:", result.message)
    return
  }
  
  // Submit the validated data
  await loginUser(result.data)
})
</script>

3. Reactive Form State

const form = $form("login")

// Access form values
console.log(form.input.value) // { email: "...", password: "..." }

// Check form mode
console.log(form.mode.value) // "idle" | "success" | "error"

// Validate manually
const result = form.validate()
if (result.ok) {
  console.log("Valid data:", result.data)
}

// Set form values
form.set({ email: "user@example.com" })

// Clear form
form.clear() // or form.clear(["input", "errors"])

Architecture

Form Definition

Forms are defined using the defineArkform function, which takes a schema definition object:

const { $form, $field } = defineArkform({
  contact: {
    schema: arktype({
      name: "string",
      email: "string.email", 
      message: "string"
    })
  },
  login: {
    schema: arktype({
      email: "string.email",
      password: "string"
    })
  }
})

State Management

Each form and field maintains its own reactive state using Nuxt's useState:

• Forms: arkform:form:${formName}
• Fields: arkform:input:${formName}:${inputName}

This ensures state persistence across HMR and component remounts.

Component Integration

Arkform provides Vue components that automatically integrate with the form state:

• <arkform> - Form wrapper with theme support
• <field> - Input fields with automatic binding
• <ark-errors> - Error display component
• <ark-messages> - Success message component

API Reference

$form

Find out more here

$field

Find out more here

Submitting Forms

Find out more here