https://github.com/benjamincharity/react-step-form
https://github.com/benjamincharity/react-step-form
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/benjamincharity/react-step-form
- Owner: benjamincharity
- License: mit
- Created: 2025-02-19T23:49:35.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-03-11T12:28:12.000Z (3 months ago)
- Last Synced: 2025-03-11T13:33:28.971Z (3 months ago)
- Language: TypeScript
- Size: 148 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# react-step-form
A flexible and animated multi-step form component for React applications. Features include:
- 🎨 Customizable welcome and completion screens
- ✨ Smooth transitions between steps
- 📱 Mobile-friendly with touch/swipe support
- ⌨️ Keyboard navigation
- ✅ Form validation with Zod
- 💾 Progress auto-save
- 🎯 TypeScript support
## Installation
Install the package:
```bash
npm install @benjc/react-step-form
```
Install the peer dependencies:
```bash
npm install framer-motion
```
## Usage
### TypeScript Interfaces
```tsx
interface Step {
component: ComponentType>
id: string
isOptional?: boolean
}
interface StepProps {
initialData?: T
isActive: boolean
onStepComplete: (result: { isComplete: boolean; stepData: T }) => void
stepId: string
submitButtonProps?: { className?: string }
validate?: (validateFn: () => Promise) => void
}
```
Basic usage example:
```tsx
import { StepForm } from '@benjc/react-step-form'
interface NameFormData {
name: string
}
const NameStep = ({ onStepComplete, validate }) => {
const { register, handleSubmit } = useForm()
return (
onStepComplete({ isComplete: true, stepData: data }))}>
Next
)
}
const EmailStep = ({ onStepComplete }) => {
const { register, handleSubmit } = useForm()
return (
onStepComplete({ isComplete: true, stepData: data }))}>
Next
)
}
function App() {
return (
console.log('Form completed:', data)}
/>
)
}
```
## Customization
### Welcome Screen
You can customize the welcome screen either with a component or configuration object:
```tsx
// Using a custom component
(
Welcome!
Start
)}
// ...
/>
// Using configuration object
```
### Completion Screen
Similarly, customize the completion screen:
```tsx
```
### Styling
Customize the appearance using className props:
```tsx
```
### Form Validation
The StepForm supports two levels of validation:
> Note: All validation examples fully support TypeScript, providing type safety for your form data.
1. **Step-Level Validation** - Individual step validation using react-hook-form:
```tsx
const ValidatedStep = ({ onStepComplete, validate }) => {
const {
register,
handleSubmit,
trigger,
getValues,
} = useForm({
resolver: zodResolver(schema),
mode: 'onChange',
})
// Register validation function
React.useEffect(() => {
if (validate) {
validate(async () => {
const isValid = await trigger()
if (isValid) {
return true
}
return false
})
}
}, [validate, trigger])
const onSubmit = handleSubmit((data) => {
onStepComplete({ isComplete: true, stepData: data })
})
return (
Next
)
}
```
2. **Form-Level Validation** - Validate across all steps:
```tsx
const schemas = {
personal: z.object({
name: z.string().min(2),
email: z.string().email(),
}),
address: z.object({
address: z.string().min(5),
city: z.string().min(2),
}),
}
const validateStep = (stepId: string, stepData: unknown) => {
const schema = schemas[stepId]
if (!schema) return true
try {
schema.parse(stepData)
return true
} catch (error) {
return false
}
}
```
Key validation behaviors:
- Steps validate on navigation attempts (next button, scroll, swipe)
- Steps are marked complete only on explicit submission
- Form data persists when navigating between steps
- Users can freely move between completed steps
## Form State Persistence
The form automatically saves progress to localStorage:
- Progress is saved after each step completion
- Form state is restored when returning to the form
- State is cleared after successful form completion
- Each form instance can be uniquely identified with an optional `id` prop
```tsx
```
## Props
| Prop | Type | Description |
| -------------------- | ------------------------------------- | ------------------------------- |
| `id` | `string` | Unique form identifier |
| `steps` | `Step[]` | Array of step configurations |
| `onComplete` | `(data: Record) => void` | Callback when form completes |
| `welcomeCover` | `Component \| Object` | Welcome screen customization |
| `completeStep` | `Component \| Object` | Completion screen customization |
| `className` | `string` | Container CSS class |
| `stepIndicatorProps` | `Object` | Step indicator styling |
| `submitButtonProps` | `Object` | Submit button styling |
| `debugMode` | `boolean` | Enable debug features |
| `validateStep` | `(stepId: string, stepData: unknown) => boolean \| Promise` | Form-level validation function |
## License
MIT