Skip to content

Commit 33eabce

Browse files
committed
Update useFieldApi page to make it seachable
1 parent 1410a5d commit 33eabce

File tree

1 file changed

+185
-11
lines changed

1 file changed

+185
-11
lines changed

packages/react-renderer-demo/src/pages/hooks/use-field-api.md

Lines changed: 185 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,16 @@
11
import DocPage from '@docs/doc-page';
2-
import InputMeta from '../input-meta.md';
32

43
<DocPage>
54

65
# useFieldApi
76

8-
React form renderer is using [react-final-form](https://github.com/final-form/react-final-form) for form state management.
9-
Most of its features are not directly available for consistency and performance reasons. If you want to create any custom
10-
components, you can access these features via `FieldProvider` component or `useFieldApi` hook.
7+
This hook is the main way for connecting custom components to the form state. (You can also access these features via `FieldProvider`, but it's not recommended.) You can read more about that in [Component mapping](/mappers/custom-mapper).
118

12-
`FieldProvider` is a wrapper using `useFieldApi` to get the access to the form state.
13-
14-
`useFieldApi` is a wrapper around [React Final Form useField hook](https://final-form.org/docs/react-final-form/api/useField).
15-
16-
You can read more about that in [Component mapping](/mappers/custom-mapper).
9+
Data Driven Forms is using [react-final-form](https://github.com/final-form/react-final-form) for form state management. Most of its features are not directly available for consistency and performance reasons. `useFieldApi` is a wrapper around [React Final Form useField hook](https://final-form.org/docs/react-final-form/api/useField).
1710

1811
## Usage
1912

20-
Next example shows simple input field with label and error message.
13+
Next example shows simple input field with a label and an error message.
2114

2215
```jsx
2316
import React from 'react';
@@ -39,6 +32,187 @@ const NewComponent = (props) => {
3932
export default NewComponent
4033
```
4134

42-
<InputMeta />
35+
## What are input and meta?
36+
37+
### Input
38+
39+
Input is an object which contains field values and methods that change form state. See the selection of most important attributes:
40+
41+
#### value
42+
43+
*any*
44+
45+
Any value of given form field. Its data type is based on field data type.
46+
47+
#### name
48+
49+
*string*
50+
51+
An unique name of form field. Value will be accessible under this key in form state.
52+
53+
54+
#### onBlur
55+
56+
*() => void*
57+
58+
A function that should be triggered on field blur event.
59+
60+
#### onChange
61+
62+
*(value | event: any) => void*
63+
64+
A function that changes value of field in formState. Should be called whenever you want to change value of field.
65+
66+
#### onFocus
67+
68+
*() => void*
69+
70+
A function that should be triggered on field focus event.
71+
72+
Every user interaction that updates field value in form state should also call `input.onChange` with correct value.
73+
74+
#### Usage of input
75+
76+
**HTML Input elements**
77+
78+
Just spread the input object on element. Input methods are mapped 1:1 to React functions.
79+
80+
```jsx
81+
import React from 'react';
82+
83+
import { useFieldApi } from '@data-driven-forms/react-form-renderer';
84+
85+
const TextField = (props) => {
86+
const { input } = useFieldApi(props);
87+
88+
return <input {...rest}>
89+
}
90+
```
91+
92+
**Custom elements**
93+
94+
If you have non-input element, you can still easily use all the methods.
95+
96+
```jsx
97+
import React from 'react';
98+
99+
import { useFieldApi } from '@data-driven-forms/react-form-renderer';
100+
101+
import Card from './custom-card.js';
102+
103+
const TextField = (props) => {
104+
const { input } = useFieldApi(props);
105+
106+
return <Card onClick={() => input.onChange(props.value)}>
107+
}
108+
```
109+
110+
---
111+
112+
### Meta
113+
114+
Meta is a object which contains meta information about field with given name. There is a lot of information about every field.
115+
[Full list is here](https://final-form.org/docs/react-final-form/types/FieldRenderProps#metaactive). These are commonly used meta informations:
116+
117+
#### error
118+
119+
*any*
120+
121+
Whatever your validation function returns.
122+
123+
#### pristine
124+
125+
*boolean*
126+
127+
True if the current value is === to the initial value, false if the values are !==.
128+
129+
#### dirty
130+
131+
*boolean*
132+
133+
The opposite of pristine.
134+
135+
#### touched
136+
137+
*boolean*
138+
139+
True if this field has ever gained and lost focus. false otherwise. Useful for knowing when to display error messages.
140+
141+
#### valid
142+
143+
*boolean*
144+
145+
True if this field has no validation or submission errors. False otherwise.
146+
147+
#### validating
148+
149+
*boolean*
150+
151+
True if this field is currently being validated. False otherwise.
152+
153+
#### Usage of meta
154+
155+
The main reason why to use meta object is to show users additional information about the field.
156+
157+
**Validating field**
158+
159+
```jsx
160+
import React from 'react';
161+
162+
import { useFieldApi } from '@data-driven-forms/react-form-renderer';
163+
164+
import Spinner from './spinner.js';
165+
166+
const TextField = (props) => {
167+
const { input, meta } = useFieldApi(props);
168+
169+
return <React.Fragment>
170+
<input {...rest}>
171+
{meta.validating && <Spinner />}
172+
</React.Fragment>
173+
}
174+
```
175+
176+
**Error**
177+
178+
```jsx
179+
import React from 'react';
180+
181+
import { useFieldApi } from '@data-driven-forms/react-form-renderer';
182+
183+
import ErrorMessage from './error-message.js';
184+
185+
const TextField = (props) => {
186+
const { input, meta } = useFieldApi(props);
187+
188+
return <React.Fragment>
189+
<input {...rest}>
190+
{meta.error && <ErrorMessage error={meta.error} />}
191+
</React.Fragment>
192+
}
193+
```
194+
195+
**Error after touched**
196+
197+
This combination makes the UX better, as users won't see an error until they finishes typing.
198+
199+
```jsx
200+
import React from 'react';
201+
202+
import { useFieldApi } from '@data-driven-forms/react-form-renderer';
203+
204+
import ErrorMessage from './error-message.js';
205+
206+
const TextField = (props) => {
207+
const { input, meta } = useFieldApi(props);
208+
209+
const error = meta.touched && meta.error;
210+
211+
return <React.Fragment>
212+
<input {...rest}>
213+
{error && <ErrorMessage error={error} />}
214+
</React.Fragment>
215+
}
216+
```
43217

44218
</DocPage>

0 commit comments

Comments
 (0)