🚀 use-lite-form

A lightweight, type-safe form management library for React with a powerful and intuitive API.

✨ Features

• 🪶 Lightweight - Less than 3KB gzipped
• 🧩 Simple API - Intuitive component-based interface
• 🔄 Controlled Forms - Seamless state management
• 💾 Nested Data - Support for complex, nested form structures
• 🧪 Validation - Flexible validation with custom error messages
• 🔀 Dynamic Fields - Add, remove, reorder form items
• ⚡ Value Transformations - Transform inputs and outputs
• 🧠 Type-Safe - Full TypeScript support
• 🗄️ Lists Support - Arrays of objects with CRUD operations
• ↩️ Undo/Redo - Built-in support for form state history

📦 Installation

1npm install use-lite-form
2
3# or with yarn
4yarn add use-lite-form
5
6# or with pnpm
7pnpm add use-lite-form

🚦 Quick Start

1import { useState } from 'react';
2import Form from 'use-lite-form';
3
4const BasicForm = () => {
5	const [formResult, setFormResult] = useState(null);
6
7	const handleSubmit = payload => {
8		setFormResult(payload.value);
9	};
10
11	return (
12		<div>
13			<Form onSubmit={handleSubmit}>
14				<div>
15					<label>Full Name</label>
16					<Form.Item
17						path={['name']}
18						required
19					>
20						<input type='text' />
21					</Form.Item>
22				</div>
23
24				<div>
25					<label>Email</label>
26					<Form.Item
27						path={['email']}
28						required
29					>
30						<input type='email' />
31					</Form.Item>
32				</div>
33
34				<button type='submit'>Submit</button>
35			</Form>
36
37			{formResult && <pre>{JSON.stringify(formResult, null, 2)}</pre>}
38		</div>
39	);
40};

📖 API Reference

<Form>

The main component that provides the form context.

1<Form
2	onSubmit={payload => console.log(payload.value)}
3	onChange={payload => console.log(payload.value, payload.errors)}
4	value={initialValues}
5>
6	{/* Form content */}
7</Form>

Props

• onSubmit: Function called when the form is submitted
• onChange: Function called when any form field changes
• value: Initial form values
• form: Custom form instance (advanced usage)
• locked: Whether the form is locked for editing
• as: HTML element to render the form as (default: 'form')

<Form.Item>

Component for individual form fields.

1<Form.Item
2	path={['user', 'name']}
3	required
4	defaultValue=''
5>
6	<input type='text' />
7</Form.Item>

Props

• childTransform: Transforms the value for the child component only, without affecting the form state
• path: Array path specifying the location of this field's value within the form state
• required: Boolean or validation function that determines if the field is required and returns error messages
• defaultValue: Initial value used when the field has no value in the form state
• debounce: Delay in milliseconds before reporting value changes to the form (default: 250ms)
• transformIn: Transforms the value when reading from form state
• transformOut: Transforms the value when writing to form state
• effect: Side effect function executed whenever the field value changes in the form state

<Form.List>

Component for managing arrays of form items.

1<Form.List path={['items']}>
2	<Form.List.Items>
3		{props => (
4			<div>
5				<Form.Item path={[...props.path, 'name']}>
6					<input type='text' />
7				</Form.Item>
8				<button onClick={() => props.remove()}>Remove</button>
9			</div>
10		)}
11	</Form.List.Items>
12
13	<Form.List.Add>{props => <button onClick={() => props.add({ name: '' })}>Add Item</button>}</Form.List.Add>
14</Form.List>

<Form.Value>

Component to display or use form values in your UI.

1<Form.Value path={['user', 'type']}>
2	{({ value }) => {
3		if (value === 'admin') {
4			return <div>Admin Fields...</div>;
5		}
6		return <div>User Fields...</div>;
7	}}
8</Form.Value>

Form.useForm()

Hook to access the form instance and values.

1const MyComponent = () => {
2	const { instance, value } = Form.useForm(['user']);
3
4	// Access specific path value
5	console.log(value.name);
6
7	// Call form methods
8	instance.set(['user', 'name'], 'New Value');
9
10	return <div>...</div>;
11};

Form.useNewForm(initialValue?: object)

Hook to create a new form instance.

1const MyComponent = () => {
2	const { instance, value } = Form.useNewForm({ name: 'Felipe' });
3
4	// Access specific path value
5	console.log(value.name);
6
7	// Call form methods
8	instance.set(['user', 'name'], 'New Value');
9
10	return <div>...</div>;
11};

Form.useFormHistory(options?: object)

A hook to manage the form's value history, enabling undo and redo functionality. It must be used within a <Form> component.

1const HistoryControls = () => {
2	const { canRedo, canUndo, redo, undo, clear } = Form.useFormHistory({
3		maxCapacity: 20 // Optional: defaults to 10
4	});
5
6	return (
7		<div>
8			<button
9				onClick={undo}
10				disabled={!canUndo}
11			>
12				Undo
13			</button>
14			<button
15				onClick={redo}
16				disabled={!canRedo}
17			>
18				Redo
19			</button>
20			<button onClick={clear}>Clear History</button>
21		</div>
22	);
23};
24
25const MyForm = () => {
26	return (
27		<Form>
28			<HistoryControls />
29			{/* Form.Item fields go here */}
30		</Form>
31	);
32};

Options

• maxCapacity (optional, number): The maximum number of history states to store. Defaults to 10.
• debounceTime (optional, number): Time in milliseconds to debounce history updates.

Returns

• canUndo (boolean): True if there is a past state to revert to.
• canRedo (boolean): True if there is a future state to restore.
• undo() (function): Reverts the form to the previous state.
• redo() (function): Restores the next state in the history.
• clear() (function): Clears the entire history.

🎯 Advanced Usage

Custom Validation

1<Form.Item
2	path={['password']}
3	required={({ value }) => {
4		if (value.length < 8) {
5			return 'Password must be at least 8 characters';
6		}
7		if (!/[A-Z]/.test(value)) {
8			return 'Password must contain at least one uppercase letter';
9		}
10		if (!/[0-9]/.test(value)) {
11			return 'Password must contain at least one number';
12		}
13		return false;
14	}}
15>
16	<input type='password' />
17</Form.Item>

Value Transformations

1<Form.Item
2	path={['tags']}
3	defaultValue={[]}
4	transformIn={({ value }) => (Array.isArray(value) ? value.join(', ') : '')}
5	transformOut={({ value }) =>
6		value
7			.split(',')
8			.map(tag => tag.trim())
9			.filter(Boolean)
10	}
11>
12	<input
13		type='text'
14		placeholder='tag1, tag2, tag3'
15	/>
16</Form.Item>

Conditional Rendering

1<Form.Item
2  path={['contactMethod']}
3  defaultValue="email"
4>
5  {/* Radio buttons for contact method */}
6</Form.Item>
7
8<Form.Value path={['contactMethod']}>
9  {({ value }) => {
10    if (value === 'email') {
11      return (
12        <Form.Item path={['emailAddress']} required>
13          <input type="email" />
14        </Form.Item>
15      );
16    }
17    if (value === 'phone') {
18      return (
19        <Form.Item path={['phoneNumber']} required>
20          <input type="tel" />
21        </Form.Item>
22      );
23    }
24    return null;
25  }}
26</Form.Value>

Dynamic Lists

1<Form.List path={['items']}>
2	<Form.List.Items>
3		{props => (
4			<div>
5				<Form.Item
6					path={[...props.path, 'name']}
7					required
8				>
9					<input type='text' />
10				</Form.Item>
11				<Form.Item
12					path={[...props.path, 'quantity']}
13					defaultValue={1}
14				>
15					<input
16						type='number'
17						min='1'
18					/>
19				</Form.Item>
20				<div>
21					<button
22						onClick={() => props.moveUp()}
23						disabled={props.first}
24					>
25						Move Up
26					</button>
27					<button
28						onClick={() => props.moveDown()}
29						disabled={props.last}
30					>
31						Move Down
32					</button>
33					<button onClick={() => props.remove()}>Remove</button>
34				</div>
35			</div>
36		)}
37	</Form.List.Items>
38
39	<Form.List.Add>{props => <button onClick={() => props.add({ name: '', quantity: 1 })}>Add Item</button>}</Form.List.Add>
40</Form.List>

Undo/Redo with useFormHistory

Implement undo/redo functionality by creating a control component that uses the Form.useFormHistory hook.

1import Form from 'use-lite-form';
2
3// A component to manage history controls
4const HistoryControls = () => {
5	const { canRedo, canUndo, redo, undo } = Form.useFormHistory();
6
7	return (
8		<div>
9			<button
10				type='button'
11				onClick={undo}
12				disabled={!canUndo}
13			>
14				Undo
15			</button>
16			<button
17				type='button'
18				onClick={redo}
19				disabled={!canRedo}
20			>
21				Redo
22			</button>
23		</div>
24	);
25};
26
27// The main form component
28const EditorForm = () => (
29	<Form>
30		<HistoryControls />
31
32		<Form.Item
33			path={['title']}
34			debounce={500}
35		>
36			<input
37				type='text'
38				placeholder='Title'
39			/>
40		</Form.Item>
41
42		<Form.Item
43			path={['content']}
44			debounce={500}
45		>
46			<textarea placeholder='Start writing...' />
47		</Form.Item>
48
49		<button type='submit'>Save</button>
50	</Form>
51);

🧠 How It Works

use-lite-form is built around React's Context API to provide a seamless form management experience:

1. Form Instance: Manages the form state, including values and errors
2. Path-based Access: Uses array paths to access nested form data
3. Component Architecture: Uses a component-based approach for form elements
4. Validation System: Flexible validation with custom error messages
5. List Management: Special handling for arrays of form items
6. Transformations: Support for transforming data between the view and the model
7. History Management: A dedicated hook useFormHistory listens for form changes and manages a history stack for undo/redo operations.

🧪 Running Tests

1yarn test

📝 License

MIT © Felipe Rohde

👨‍💻 Author

Felipe Rohde

• Twitter: @felipe_rohde
• Github: @feliperohdee
• Email: feliperohdee@gmail.com