@chemical-x/forms NPM

Chemical X Forms

A fully type-safe, schema-driven form library that gives you superpowers.Comes with a minimal composition API that prioritizes developer experience and form correctness. 🚧 this library is not production ready yet.

🏔️ Features

Compact API – Minimal yet expressive API surface with core functions like useForm, register, and handleSubmit to reduce boilerplate.
Abstract Schema Support – Integrates with validation libraries like Zod for type-safe schemas and automatic validation.
v-register Directive – One SSR-safe directive that automatically tracks everything.
Full State Tracking – Automatically tracks field states (value, touched, dirty status, validation errors, etc).
TypeScript Friendly – Fully type-safe, with advanced form type inference from your schema.

🪩 Installation

Install with Nuxi:

npx nuxi module add @chemical-x/forms

That's it! You can now use Chemical X Forms in your Nuxt app ✨

Install manually:

# Using npm
npm install @chemical-x/forms

Then add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@chemical-x/forms"],
});

🪄 Usage

Basic Example

<script setup lang="ts">
import { z } from "zod";

// Define your schema
const schema = z.object({ planet: z.string() });

// Create your form
const { getFieldState, register, key } = useForm({ schema });

// Get the state of the 'planet' field
const planetState = getFieldState("planet");
</script>

<template>
  <div>
    <h1>Planet Form</h1>

    <input
      v-register="register('planet')"
      placeholder="Enter your favorite planet"
    />

    <p>Planet field State:</p>
    <pre>{{ JSON.stringify(planetState, null, 2) }}</pre>
    <hr />
  </div>
</template>

Core API Functions

note: detailed documentation coming soon

useForm(options?) – Initializes form state. Abstract schema required.

v-register – Custom, SSR-safe directive for registering components with Chemical X

register(name: string) – Binds a field to form state.

handleSubmit(onSubmit, onError?) – Handles submission with validation.

getValue(name: string) – Retrieves a field value.

setValue(name: string, value: any) – Updates a field programmatically.

getFieldState(name: string) – Returns field state (value, touched, errors, etc.).

🥇 Advanced Features

Fully SSR Safe – Fully Nuxt 3-compatible with hydration-safe bindings.
Validation Handling – Displays schema validation errors automatically.
Performance Optimizations – Efficient reactive updates for optimal performance.