![](.github/assets/logo.png)

Create ReactJS uncontrolled form structures with nested fields, validations and much more! 🚀

[![npm](https://img.shields.io/npm/v/@rocketseat/unform.svg?color=%237159c1)](https://www.npmjs.com/package/@rocketseat/unform) [![Travis (.org)](https://img.shields.io/travis/rocketseat/unform.svg?color=%237159c1)](https://travis-ci.org/Rocketseat/unform) [![Coverage Status](https://img.shields.io/coveralls/github/Rocketseat/unform.svg?color=%237159c1)](https://coveralls.io/github/Rocketseat/unform?branch=master)

## Overview Unform is a performance focused library that helps you creating beautiful forms in React with the power of uncontrolled components performance and React Hooks. ## Table of contents - [Key features](#key-features) - [Why not Formik, Redux Form or another library?](#why-not-formik-redux-form-or-another-library) - [Roadmap](#roadmap) - [Installation](#installation) - [Guides](#guides) - [Basics](#basics) - [Elements](#elements) - [Input element](#input-element) - [Select element](#select-element) - [File Input element](#file-input-element) - [Choice element](#choice-element) - [Check element](#check-element) - [Reset Form](#reset-form) - [Nested fields](#nested-fields) - [Initial data](#initial-data) - [Validation](#validation) - [Styling](#styling) - [Manipulate data](#manipulate-data) - [Custom elements](#custom-elements) - [React select](#react-select) - [React datepicker](#react-datepicker) - [Contributing](#contributing) - [Contribution Guidelines](#contribution-guidelines) - [Code of Conduct](#code-of-conduct) - [Need help?](#need-help) - [License](#license) ## Key features - Beautiful syntax; - React Hooks 😍; - Performance focused; - Use of uncontrolled components; - Integration with pickers, dropdowns and other libraries; ## Why not Formik, Redux Form or another library? Formik/Redux Form has a really great syntax while it has a really poor support to uncontrolled components and deep nested data structures. With unform it's easy to create forms with complex relationships without losing performance. ## Roadmap - Native checkbox/radio support; - React Native support (should we?); - Better docs; ## Installation Just add unform to your project: ``` yarn add @rocketseat/unform ``` ## Guides ### Basics Unform exposes two default form elements: `` and `` element does not support multiple values, you can use [React Select](#react-select) example to achieve that. ```js import React from 'react'; import { Form, Input } from '@rocketseat/unform'; function App() { function handleSubmit(data) { console.log(data); /** * { * email: 'email@example.com', * password: '123456' * } */ } return ( ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

### Elements Unform exposes two elements by default, Input and Select. #### Input element Input elements can receive a `multiline` prop that will render a textarea instead. ```js import React from 'react'; import { Form, Input } from '@rocketseat/unform'; function App() { function handleSubmit(data) {} return ( ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

#### Select element Every ` ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

#### File Input element FileInput components may receive an `onStartProgress` property that will be called when file loading starts. ```js import React from 'react'; import { Form, FileInput } from '@rocketseat/unform'; function App() { function handleSubmit(data) {} function handleProgress(progress, event) {} return (

); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

#### Choice element Choice element represents multiple options elements. The `options` property is the options list, and is necessary. It will display checkboxes or radio buttons based on `multiple` property. To display multiple checkboxes: ```js import React from 'react'; import { Form, Choice } from '@rocketseat/unform'; function App() { function handleSubmit(data) {} function handleProgress(progress, event) {} return (

); } ``` When the value is returned, the format is an array of selected values (_..., fieldName: ['1', '2', ...], ..._). To display multiple radio buttons: ```js import React from 'react'; import { Form, Choice } from '@rocketseat/unform'; function App() { function handleSubmit(data) {} function handleProgress(progress, event) {} return (

); } ``` When the value is returned in this case, the format will be the value selected (_..., fieldName: '1', ..._). **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

#### Check element This component display only one option in form of a single checkbox. ```js import React from 'react'; import { Form, Check } from '@rocketseat/unform'; function App() { function handleSubmit(data) {} return (

); } ``` The value of this element will be true if checked or false otherwise (_..., fieldName: true, ..._). **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

### Reset form ```js import React from 'react'; import { Form, Input } from '@rocketseat/unform'; function App() { function handleSubmit(data, { resetForm }) { resetForm(); } return ( ); } ``` _Optional:_ `resetForm` may receive an object that will be applied when the form is reset. ```js import React from 'react'; import { Form, Input } from '@rocketseat/unform'; const options = [ { id: 'react', title: 'ReactJS' }, { id: 'node', title: 'NodeJS' }, { id: 'rn', title: 'React Native' }, ]; function App() { function handleSubmit(data, { resetForm }) { resetForm({ tech: 'react' }); } return ( ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

### Initial data _Optional_: Here you can set what the initial data for each field will be, you store the initial field values into a variable and load it in the `Form` using the prop `initialData`. ```js import React from 'react'; import { Form, Input, Scope } from '@rocketseat/unform'; function App() { const initialData = { name: 'John Doe', address: { street: 'Sample Avenue', }, }; function handleSubmit(data) {} return ( ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

### Validation > When you define your schema to validation, only data defined in it will be sent to `data` in `onSubmit` event even though there are other fields. ```js import React from 'react'; import { Form, Input } from '@rocketseat/unform'; import * as Yup from 'yup'; const schema = Yup.object().shape({ email: Yup.string() .email('Custom invalid email message') .required('Custom required message'), password: Yup.string() .min(4) .required(), }); function App() { function handleSubmit(data) {} return ( ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

### Styling The `Form` component exposes two props for that: `style` and `className`. You can use any `CSS-in-JS` library to style your form or just pass the class name string, or even the `style` object directly! For example: ```js import styled from 'styled-components'; // or emotion, for example // weird choice for a background color, huh? export default styled(MyForm)` background: red; `; ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

### Manipulate data ```js import React, { useState } from 'react'; import { Form, Input } from '@rocketseat/unform'; import * as Yup from 'yup'; const schema = Yup.object().shape({ name: Yup.string().required(), email: Yup.string() .email() .required(), password: Yup.string().when('$updatePassword', { is: true, then: Yup.string() .min(4) .required(), otherwise: Yup.string().strip(true), }), }); function App() { const [updatePassword, setUpdatePassword] = useState(false); const initialData = { name: 'John Doe', email: 'johndoe@example.com', }; function handleSubmit(data) {} return ( ); } ``` **↑ back to:** [Table of contents](#table-of-contents) · [Guides](#guides)

## Custom elements Sometimes we need to use third-party component in our forms. But don't you worry, Unform has your back! You can do that via `useField` which provides all the resources you need to use your component with Unform. Below are some examples with [react-select](https://github.com/JedWatson/react-select) and [react-datepicker](https://github.com/Hacker0x01/react-datepicker/). _Observation_: If you are using Eslint + Prettier you need to take care with your `useEffect` dependecies, probably they will change when you format your code. To fix that you can add a comment on the line above of your `useEffect` dependencies disabling the eslint on that line. You can just follow the example below. _Example:_ ```js useEffect(() => { registerField(); }, [ref.current, fieldName]); // eslint-disable-line ``` ### React select ```js import React, { useRef, useEffect } from 'react'; import Select from 'react-select'; import { useField } from '@rocketseat/unform'; export default function ReactSelect({ name, label, options, multiple, ...rest }) { const ref = useRef(null); const { fieldName, registerField, defaultValue, error } = useField(name); function parseSelectValue(selectRef) { const selectValue = selectRef.state.value if (!multiple) { return selectValue ? selectValue.id : ''; } return selectValue ? selectValue.map(option => option.id) : []; } useEffect(() => { registerField({ name: fieldName, ref: ref.current, path: 'state.value', parseValue: parseSelectValue, clearValue: selectRef => { selectRef.select.clearValue(); }, }); }, [ref.current, fieldName]); // eslint-disable-line function getDefaultValue() { if (!defaultValue) return null; if (!multiple) { return options.find(option => option.id === defaultValue); } return options.filter(option => defaultValue.includes(option.id)); } return ( <> {label && {label}}

	Stars	Issues	Version	Updated	Created
@rocketseat/unform			1.6.2	4 years ago	5 years ago
formik			2.4.6	25 days ago	7 years ago
react-form	3,372	51	4.0.1	5 years ago	9 years ago
react-hook-form	39,844	27	7.51.4	16 days ago	5 years ago

@rocketseat/unform vs formik vs react-form vs react-hook-form

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past