Quick start

This page explains hot 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 are a useField hook. You will use it to register fields on Unform. It will also be used to integrate with form libraries, such as React Select, React Datepicker and others.

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 a initialData);
• registerField: the method that will be used to register a form field.

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

Copy
useEffect(() => {
  registerField({
    name: fieldName,
    getValue: ref => {
      return ref.value;
    },
    ref: inputRef.current,
  });
}, [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);
• getValue: The method used to return the input value. In a simple input, we just need to return ref.value;
• ref: Input ref.

As mentioned, you are responsible for creating the UI. Here, we are just creating a simple input, but you could also add a label, a place to show a error message or anything you want. 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 also use our Form component, passing to it 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:

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';
}