Skip to content

Commit faf3ba1

Browse files
authored
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.
1 parent cec6f48 commit faf3ba1

File tree

1 file changed

+18
-14
lines changed

1 file changed

+18
-14
lines changed

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

Lines changed: 18 additions & 14 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

@@ -24,9 +24,11 @@ const formOpts = formOptions({
2424
})
2525
```
2626

27+
More information about `formOptions` can be found at [FormOptions](../../../reference/interfaces/FormOptions.md)
28+
2729
## Form Instance
2830

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.
31+
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.
3032

3133
```tsx
3234
const form = useForm({
@@ -38,7 +40,7 @@ const form = useForm({
3840
})
3941
```
4042

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

4345
```tsx
4446
interface User {
@@ -59,7 +61,7 @@ const form = useForm({
5961

6062
## Field
6163

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.
64+
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.
6365

6466
Example:
6567

@@ -79,7 +81,7 @@ Example:
7981
/>
8082
```
8183

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

8486
Example (ESLint):
8587

@@ -107,12 +109,12 @@ const {
107109
} = field.state
108110
```
109111

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

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
114+
- **isTouched**: is `true` once the user changes or blurs the field
115+
- **isDirty**: is `true` once the field's value is changed, even if it's reverted to the default. Opposite of `isPristine`
116+
- **isPristine**: is `true` until the user changes the field's value. Opposite of `isDirty`
117+
- **isBlurred**: is `true` once the field loses focus (is blurred)
116118

117119
```ts
118120
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
@@ -134,12 +136,12 @@ Persistent `dirty` state
134136

135137
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
136138

137-
- _"isDefaultValue"_, whether the field's current value is the default value
139+
- **isDefaultValue**: is `true` when the field's current value is the default value
138140

139141
```ts
140142
const { isDefaultValue, isTouched } = field.state.meta
141143

142-
// The following line will re-create the non-Persistent `dirty` functionality.
144+
// The following line will re-create the non-persistent `dirty` functionality.
143145
const nonPersistentIsDirty = !isDefaultValue
144146
```
145147

@@ -159,6 +161,8 @@ Example:
159161
/>
160162
```
161163

164+
More information on the Field API can be found at [FieldApi](../../../reference/classes/FieldApi#schema)
165+
162166
## Validation
163167

164168
`@tanstack/react-form` provides both synchronous and asynchronous validation out of the box. Validation functions can be passed to the `form.Field` component using the `validators` prop.
@@ -290,7 +294,7 @@ More information can be found at [Listeners](./listeners.md)
290294

291295
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.
292296

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.
297+
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.
294298

295299
Example:
296300

@@ -370,7 +374,7 @@ Example:
370374

371375
## Reset Buttons
372376

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.
377+
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.
374378
Use `event.preventDefault()` inside the button's `onClick` handler to prevent the native form reset.
375379

376380
Example:

0 commit comments

Comments
 (0)