grmn-se-formish

grmn-se-formish is a powerful and flexible form management library for React applications. It provides a set of components and hooks to simplify form handling, state management, and validation.

Table of Contents

• Installation
• Key Features
• Usage
  • Basic Example
  • Using Zod for Validation
• API Reference
  • Components
    • Form
    • FormContextProvider
  • Hooks
    • useForm
    • useField
    • useFormContext
• Advanced Usage
• TypeScript Support
• Contributing
• License

Installation

To install grmn-se-formish, use npm or yarn:

npm install grmn-se-formish
# or
yarn add grmn-se-formish

Key Features

• Easy form state management
• Field-level and form-level validation using Zod
• TypeScript support
• Flexible API with hooks and components
• Support for complex nested forms
• Debug mode for easier development

Usage

Basic Example

Here's a simple example of how to use grmn-se-formish:

import React from "react";
import { Form, useForm } from "grmn-se-formish";

const MyForm = () => {
  const { register, handleSubmit } = useForm();

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("name")} placeholder="Name" />
      <input {...register("email")} placeholder="Email" type="email" />
      <button type="submit">Submit</button>
    </Form>
  );
};

export default MyForm;

Using Zod for Validation

grmn-se-formish integrates seamlessly with Zod for form validation:

import React from "react";
import { Form, useForm } from "grmn-se-formish";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters"),
  email: z.string().email("Invalid email address"),
});

const MyForm = () => {
  const { register, handleSubmit, errors } = useForm({
    schema,
    validateOnChange: true,
  });

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("name")} placeholder="Name" />
      {errors.name && <span>{errors.name}</span>}
      <input {...register("email")} placeholder="Email" type="email" />
      {errors.email && <span>{errors.email}</span>}
      <button type="submit">Submit</button>
    </Form>
  );
};

export default MyForm;

API Reference

Components

Form

The `Form` component is a wrapper for your form elements. It handles form submission and provides context for form state.

Props:

• `onSubmit`: Function called when the form is submitted
• `children`: React nodes to be rendered inside the form
• `debug`: Boolean to enable debug mode
• `validateOnChange`: Boolean to enable validation on field change

FormContextProvider

The `FormContextProvider` component provides form context to its children. It's usually not needed to use this directly, as the `Form` component uses it internally.

Hooks

useForm

The `useForm` hook is the main entry point for form functionality.

const {
  values,
  errors,
  register,
  handleSubmit,
  setFieldValue,
  validateForm,
  // ... other properties and methods
} = useForm(options);

Options:

• `initialSchema`: Zod schema for form validation
• `initialValues`: Initial form values
• `validateOnChange`: Boolean to enable validation on field change
• `debug`: Boolean to enable debug mode

useField

The `useField` hook provides access to individual field state and methods.

const {
  value,
  error,
  setFieldValue,
  clearFieldValue,
  // ... other properties and methods
} = useField(name, props);

useFormContext

The `useFormContext` hook allows access to the form context from any component within the form.

const { values, errors, schema, setValues, setErrors, setSchema } =
  useFormContext(schema, initialValues, debug);

Advanced Usage

grmn-se-formish supports advanced use cases such as:

• Nested form structures
• Dynamic form fields
• Custom validation logic
• Integration with UI libraries

For more detailed examples and advanced usage, please refer to our Advanced Guide.

TypeScript Support

grmn-se-formish is written in TypeScript and provides full type definitions for all its components and hooks. This ensures type safety and improves developer experience when using the library in TypeScript projects.

Contributing

We welcome contributions to grmn-se-formish! Please see our Contributing Guide for more information on how to get started.

License

grmn-se-formish is released under the MIT License. See the LICENSE file for more details.