Skip to content

Commit d2ae76a

Browse files
[Docs] Refine language and formatting in react basic concepts guide (#1943)
* Refine language and formatting in basic concepts guide Hey team, These are some suggestions I have for how we could improve this page. It's mostly grammar and consistency fixes, but includes slight re-wording to improve clarity. I'm open to feedback. * docs(form): Removed links to references and moved `isDefaultValue` * ci: apply automated fixes and generate docs --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
1 parent cec6f48 commit d2ae76a

File tree

1 file changed

+15
-16
lines changed

1 file changed

+15
-16
lines changed

docs/framework/react/guides/basic-concepts.md

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ This page introduces the basic concepts and terminology used in the `@tanstack/r
77

88
## Form Options
99

10-
You can create options for your form so that it can be shared between multiple forms by using the `formOptions` function.
10+
You can customize your form by creating configuration options with the `formOptions` function. These options can be shared between multiple forms.
1111

1212
Example:
1313

@@ -26,7 +26,7 @@ const formOpts = formOptions({
2626

2727
## Form Instance
2828

29-
A Form Instance is an object that represents an individual form and provides methods and properties for working with the form. You create a form instance using the `useForm` hook provided by the form options. The hook accepts an object with an `onSubmit` function, which is called when the form is submitted.
29+
A Form instance is an object that represents an individual form and provides methods and properties for working with the form. You create a Form instance using the `useForm` hook provided by the form options. The hook accepts an object with an `onSubmit` function, which is called when the form is submitted.
3030

3131
```tsx
3232
const form = useForm({
@@ -38,7 +38,7 @@ const form = useForm({
3838
})
3939
```
4040

41-
You may also create a form instance without using `formOptions` by using the standalone `useForm` API:
41+
You may also create a Form instance without using `formOptions` by using the standalone `useForm` API:
4242

4343
```tsx
4444
interface User {
@@ -59,7 +59,7 @@ const form = useForm({
5959

6060
## Field
6161

62-
A Field represents a single form input element, such as a text input or a checkbox. Fields are created using the form.Field component provided by the form instance. The component accepts a name prop, which should match a key in the form's default values. It also accepts a children prop, which is a render prop function that takes a field object as its argument.
62+
A Field represents a single form input element, such as a text input or a checkbox. Fields are created using the `form.Field` component provided by the Form instance. The component accepts a `name` prop, which should match a key in the form's default values. It also accepts a `children` prop, which is a render prop function that takes a `field` object as its argument.
6363

6464
Example:
6565

@@ -79,7 +79,7 @@ Example:
7979
/>
8080
```
8181

82-
If you run into issues handing in children as props, make sure to check your linting rules.
82+
If you run into issues handling `children` as props, make sure to check your linting rules.
8383

8484
Example (ESLint):
8585

@@ -107,12 +107,13 @@ const {
107107
} = field.state
108108
```
109109

110-
There are four states in the metadata that can be useful to see how the user interacts with a field:
110+
There are four states in the metadata that can be useful for seeing how the user interacts with a field:
111111

112-
- _"isTouched"_, after the user changes the field or blurs the field
113-
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
114-
- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
115-
- _"isBlurred"_, after the field has been blurred
112+
- **isTouched**: is `true` once the user changes or blurs the field
113+
- **isDirty**: is `true` once the field's value is changed, even if it's reverted to the default. Opposite of `isPristine`
114+
- **isPristine**: is `true` until the user changes the field's value. Opposite of `isDirty`
115+
- **isBlurred**: is `true` once the field loses focus (is blurred)
116+
- **isDefaultValue**: is `true` when the field's current value is the default value
116117

117118
```ts
118119
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
@@ -132,14 +133,12 @@ Persistent `dirty` state
132133
- **Libraries**: Angular Form, Vue FormKit.
133134
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
134135

135-
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
136-
137-
- _"isDefaultValue"_, whether the field's current value is the default value
136+
We have chosen the persistent 'dirty' state model. However, we have introduced the `isDefaultValue` flag to also support a non-persistent 'dirty' state.
138137

139138
```ts
140139
const { isDefaultValue, isTouched } = field.state.meta
141140

142-
// The following line will re-create the non-Persistent `dirty` functionality.
141+
// The following line will re-create the non-persistent `dirty` functionality.
143142
const nonPersistentIsDirty = !isDefaultValue
144143
```
145144

@@ -290,7 +289,7 @@ More information can be found at [Listeners](./listeners.md)
290289

291290
Array fields allow you to manage a list of values within a form, such as a list of hobbies. You can create an array field using the `form.Field` component with the `mode="array"` prop.
292291

293-
When working with array fields, you can use the fields `pushValue`, `removeValue`, `swapValues` and `moveValue` methods to add, remove, swap, and move a value from one index to another within the array, respectively. Additional helper methods such as `insertValue`, `replaceValue`, and `clearValues` are also available for inserting, replacing, and clearing array values.
292+
When working with array fields, you can use the `pushValue`, `removeValue`, `swapValues`, and `moveValue` methods to add, remove, swap, and move a value from one index to another within the array, respectively. Additional helper methods such as `insertValue`, `replaceValue`, and `clearValues` are also available for inserting, replacing, and clearing array values.
294293

295294
Example:
296295

@@ -370,7 +369,7 @@ Example:
370369

371370
## Reset Buttons
372371

373-
When using `<button type="reset">` in conjunction with TanStack Form's `form.reset()`, you need to prevent the default HTML reset behavior to avoid unexpected resets of form elements (especially `<select>` elements) to their initial HTML values.
372+
When using `<button type="reset">` with TanStack Form's `form.reset()`, you need to prevent the default HTML reset behavior to avoid unexpected resets of form elements (especially `<select>` elements) to their initial HTML values.
374373
Use `event.preventDefault()` inside the button's `onClick` handler to prevent the native form reset.
375374

376375
Example:

0 commit comments

Comments
 (0)