Quick start

This page explains how to get started with Unform. You will learn how to build your first input and integrate with React. Remember that with Unform, you are responsible for creating the UI (markup and styles) of your form, but don't be intimidated!

Let's get started by creating a base input component.

Copy
1import React from 'react'
2
3const Input = () => {
4  return <input type="text" placeholder="Type your username" />
5}
6
7export default Input

At the heart of every form component, there is a useField hook. You will use it to register fields on Unform. You will also use it to integrate with form libraries, such as React Select, React Datepicker, etc.

Copy
1import React, { useEffect, useRef } from 'react'
2import { useField } from '@unform/core'
3
4const Input = ({ name, ...rest }) => {
5  const inputRef = useRef()
6
7  useEffect(() => {}, [])
8
9  return (
10    <input
11      name={name}
12      ref={inputRef}
13      type="text"
14      placeholder="Type your username"
15      {...rest}
16    />
17  )
18}
19
20export default Input

In the above code, we are importing useField from @unform/core. We also created an empty useEffect and passed a prop name to our input.

Remember: when creating a form component, like this input, you always need to provide a ref.

Now let's declare our useField hook passing to it as a parameter our name. It will return some methods and variables.

Copy
const { fieldName, defaultValue, registerField } = useField(name)

For this example, we have used:

• fieldName: the input name;
• defaultValue: the default value of our input (in case you provide an initialData);
• registerField: the method that we will use to register a form field.

Here's how we can use the registerField method inside our useEffect:

Copy
useEffect(() => {
  registerField({
    name: fieldName,
    ref: inputRef,
    getValue: ref => {
      return ref.current.value
    },
    setValue: (ref, value) => {
      ref.current.value = value
    },
    clearValue: ref => {
      ref.current.value = ''
    },
  })
}, [fieldName, registerField])

It is a simple method that receives a:

• name: the fieldName returned from registerField (forms that use Scope have a different value from the name you provide);
• ref: Input ref.
• getValue: The method used to return the input value. In a simple input, we need to return ref.current.value;
• setValue: Changes the input value when you use the formRef.current.setFieldValue method;
• clearValue: If you plan to use the reset property, this method will handle the logic to clear the value.

As mentioned, you are responsible for creating the UI. Here, we made a simple input, but you could also add a label, show an error message, etc. So let's continue the tutorial to use our recently created input. Start importing the Form component.

Copy
import { Form } from '@unform/web'

Now you need to create a method to handle the form submit and use our Form component, passing the submit method and a ref.

Copy
1import React, { useRef } from 'react'
2import { Form } from '@unform/web'
3
4const App = () => {
5  const formRef = useRef()
6
7  const handleFormSubmit = data => {
8    console.log(data)
9  }
10
11  return <Form ref={formRef} onSubmit={handleFormSubmit} />
12}
13
14export default App

Inside your form, import the Input and use it like so:

Copy
1import React, { useRef } from 'react'
2import { Form } from '@unform/web'
3
4import Input from '...'
5
6const App = () => {
7  const formRef = useRef()
8
9  const handleFormSubmit = data => {
10    console.log(data)
11  }
12
13  return (
14    <Form ref={formRef} onSubmit={handleFormSubmit}>
15      <Input name="username" placeholder="Choose a username" />
16
17      <button type="submit">Save</button>
18    </Form>
19  )
20}
21
22export default App

If you save the form, something like this will show on console:

Copy
{
  username: 'hey'
}

And that's it! You have successfully created your first form using Unform!