FormKit is a flexible and powerful React form handling component that simplifies form management in React applications. It provides an intuitive API for handling form submissions, data management, and server interactions.
## Features
- 🚀 Easy form state management
- 📡 Built-in API integration
- âš¡ Custom fetch support
- 🔄 Automatic form data handling
- 🎯 TypeScript support
- 🎨 Flexible child component rendering
- 🔒 Automatic loading state management
- 🔌 Third-party component integration
## Installation
```bash
npm install formkit-react
```
```bash
yarn add formkit-react
```
## Basic Usage
```tsx
import { FormKit } from "formkit-react";
interface LoginForm {
email: string;
password: string;
}
function LoginComponent() {
return (
url="/api/login"
onSuccess={(response) => console.log("Login successful:", response)}
onError={(error) => console.error("Login failed:", error)}
>
);
}
```
## Props
| Prop | Type | Description |
| ------------- | ---------------------------------------- | ------------------------------------------------ |
| `url` | `string` | API endpoint for form submission |
| `action` | `"POST" \| "PUT" \| "DELETE" \| "PATCH"` | HTTP method for the request (default: "POST") |
| `onSubmit` | `(data: T) => void` | Callback before form submission |
| `onSuccess` | `(response: any) => void` | Callback on successful submission |
| `onError` | `(error: any) => void` | Callback on submission error |
| `initalData` | `T & Record` | Initial form data |
| `customFetch` | `(data: T) => Promise` | Custom fetch function |
| `submitText` | `string` | Text for submit button (default: "Submit") |
| `loadingText` | `string` | Text while submitting (default: "Submitting...") |
| `defaultSubmitBtn` | `boolean` | Show/hide default submit button (default: true) |
## useFormKit Hook
FormKit provides a `useFormKit` hook to manage form state and interactions programmatically.
### Usage
```tsx
import { useFormKit } from "formkit-react";
interface ProfileForm {
username: string;
bio: string;
}
function ProfileFormComponent() {
const { isLoading, error, reset } = useFormKit();
return (
);
}
```
### Hook Return Values
| Return Value | Type | Description |
| ------------- | ----------------------------- | -------------------------------------------------- |
| `isLoading` | `boolean` | Indicates if the form is being submitted |
| `error` | `unknown` | Error object if submission fails |
| `reset` | `(params?: any) => void` | Function to reset the form state |
## Form Controllers
FormKit provides a `FormKitController` component that makes it easy to integrate third-party form components. This controller handles the value management and data synchronization with the main form.
### Controller Usage
```tsx
import { FormKit } from "formkit-react";
import { FormKitController } from "formkit-react/controller";
import DatePicker from "react-third-party-datepicker";
import Select from "react-third-party-select";
interface MyFormData {
date: Date;
options: { value: string; label: string }[];
}
function MyForm() {
return (
url="/api/submit">
{/* DatePicker Integration */}
(
)}
/>
{/* React-Select Integration */}
(
)}
/>
);
}
```
### Controller Props
The `FormKitController` component accepts the following props:
```tsx
interface ControllerProps {
name: string; // Field name in the form data
render: (props: {
value: T;
onChange: (value: T) => void;
}) => React.ReactElement;
}
```
### Custom Component Integration
You can integrate any third-party component that accepts value and onChange props:
```tsx
// Example with a custom Rich Text Editor
(
)}
/>
```
### Type Safety
The controller is fully typed and supports generic types:
```tsx
interface EditorValue {
content: string;
format: "html" | "markdown";
}
name="editor"
render={({ value, onChange }) => (
onChange({ content, format: "html" })}
/>
)}
/>;
```
## Advanced Usage
## Custom Fetch Handling
```tsx
interface UserForm {
username: string;
email: string;
}
function UserRegistration() {
const handleCustomFetch = async (data: UserForm) => {
// Example of custom API integration
const response = await fetch("https://api.example.com/users", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${localStorage.getItem("token")}`,
},
body: JSON.stringify(data),
});
if (!response.ok) {
throw new Error("Registration failed");
}
return response.json();
};
return (
customFetch={handleCustomFetch}
onSuccess={(response) => console.log("Success:", response)}
onError={(error) => console.error("Error:", error)}
>
);
}
```
### With Initial Data
```tsx
interface ProfileForm {
username: string;
bio: string;
}
function ProfileEditor() {
const initialData: ProfileForm = {
username: "johndoe",
bio: "Hello world!",
};
return (
url="/api/profile" action="PATCH" initalData={initialData}>
);
}
```
## TypeScript Support
FormKit is written in TypeScript and provides full type safety. You can specify the form data type using generics:
```tsx
interface MyFormData {
name: string;
email: string;
age: number;
}
url="/api/submit"
onSubmit={(data) => {
// data is typed as MyFormData
console.log(data.name); // TypeScript knows this exists
}}
>
{/* form fields */}
;
```
## Error Handling
FormKit provides comprehensive error handling through the `onError` prop:
```tsx
{
if (error.message === "Network response was not ok") {
// Handle network errors
}
// Handle other errors
}}
>
{/* form fields */}
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.