Skip to content

Commit 77acb33

Browse files
docs: corrected field state definitions (#1540)
Co-authored-by: Harry Whorlow <whorlowharry@gmail.com> Co-authored-by: Harry Whorlow <79278353+harry-whorlow@users.noreply.github.com>
1 parent 82d7583 commit 77acb33

8 files changed

Lines changed: 182 additions & 29 deletions

File tree

-13.5 KB
Loading

docs/assets/field-states.png

-8.8 KB
Loading

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

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,21 +40,51 @@ Each field has its own state, which includes its current value, validation statu
4040

4141
Example:
4242

43-
```tsx
43+
```ts
4444
const {
4545
value,
4646
meta: { errors, isValidating },
4747
} = field.state
4848
```
4949

50-
There are three field states can be very useful to see how the user interacts with a field. A field is _"touched"_ when the user clicks/tabs into it, _"pristine"_ until the user changes value in it, and _"dirty"_ after the value has been changed. You can check these states via the `isTouched`, `isPristine` and `isDirty` flags, as seen below.
50+
There are four states in the metadata that can be useful to see how the user interacts with a field:
5151

52-
```tsx
53-
const { isTouched, isPristine, isDirty } = field.state.meta
52+
- _"isTouched"_, after the user changes the field or blurs the field
53+
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of _"isPristine"_
54+
- _"isPristine"_, until the user changes the field value. Opposite of _"isDirty"_
55+
- _"isBlurred"_, after the field has been blurred
56+
57+
```ts
58+
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
5459
```
5560

5661
![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
5762

63+
## Understanding 'isDirty' in Different Libraries
64+
65+
Non-Persistent `dirty` state
66+
67+
- **Libraries**: React Hook Form (RHF), Formik, Final Form.
68+
- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again.
69+
70+
Persistent `dirty` state
71+
72+
- **Libraries**: Angular Form, Vue FormKit.
73+
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
74+
75+
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
76+
77+
- _"isDefaultValue"_, whether the field's current value is the default value
78+
79+
```ts
80+
const { isDefaultValue, isTouched } = field.state.meta
81+
82+
// The following line will re-create the non-Persistent `dirty` functionality.
83+
const nonPersistentIsDirty = !isDefaultValue
84+
```
85+
86+
![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png)
87+
5888
## Field API
5989

6090
The Field API is an object accessed in the `tanstackField.api` property when creating a field. It provides methods for working with the field's state.

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

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -86,17 +86,47 @@ For Example:
8686

8787
Each field has its own state, which includes its current value, validation status, error messages, and other metadata. You can access a field's state using its `field.state` property.
8888

89-
```tsx
89+
```ts
9090
const {
9191
value,
9292
meta: { errors, isValidating },
9393
} = field.state
9494
```
9595

96-
There are three field states can be very useful to see how the user interacts with a field. A field is _"touched"_ when the user clicks/tabs into it, _"pristine"_ until the user changes value in it, and _"dirty"_ after the value has been changed. You can check these states via the `isTouched`, `isPristine` and `isDirty` flags, as seen below.
96+
There are four states in the metadata that can be useful to see how the user interacts with a field:
9797

98-
```tsx
99-
const { isTouched, isPristine, isDirty } = field.state.meta
98+
- _"isTouched"_, after the user changes the field or blurs the field
99+
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
100+
- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
101+
- _"isBlurred"_, after the field has been blurred
102+
103+
```ts
104+
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
100105
```
101106

102107
![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
108+
109+
## Understanding 'isDirty' in Different Libraries
110+
111+
Non-Persistent `dirty` state
112+
113+
- **Libraries**: React Hook Form (RHF), Formik, Final Form.
114+
- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again.
115+
116+
Persistent `dirty` state
117+
118+
- **Libraries**: Angular Form, Vue FormKit.
119+
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
120+
121+
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
122+
123+
- _"isDefaultValue"_, whether the field's current value is the default value
124+
125+
```ts
126+
const { isDefaultValue, isTouched } = field.state.meta
127+
128+
// The following line will re-create the non-Persistent `dirty` functionality.
129+
const nonPersistentIsDirty = !isDefaultValue
130+
```
131+
132+
![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png)

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

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -85,21 +85,22 @@ Each field has its own state, which includes its current value, validation statu
8585

8686
Example:
8787

88-
```tsx
88+
```ts
8989
const {
9090
value,
9191
meta: { errors, isValidating },
9292
} = field.state
9393
```
9494

95-
There are three states in the metadata that can be useful to see how the user interacts with a field:
95+
There are four states in the metadata that can be useful to see how the user interacts with a field:
9696

97-
- _"isTouched"_, after the user clicks/tabs into the field
98-
- _"isPristine"_, until the user changes the field value
99-
- _"isDirty"_, after the fields value has been changed
97+
- _"isTouched"_, after the user changes the field or blurs the field
98+
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
99+
- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
100+
- _"isBlurred"_, after the field has been blurred
100101

101-
```tsx
102-
const { isTouched, isPristine, isDirty } = field.state.meta
102+
```ts
103+
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
103104
```
104105

105106
![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
@@ -116,10 +117,12 @@ Persistent `dirty` state
116117
- **Libraries**: Angular Form, Vue FormKit.
117118
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
118119

119-
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce the isDefault flag. This flag acts as an inverse of the non-persistent 'dirty' state.
120+
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
120121

121-
```tsx
122-
const { isTouched, isPristine, isDirty, isDefaultValue } = field.state.meta
122+
- _"isDefaultValue"_, whether the field's current value is the default value
123+
124+
```ts
125+
const { isDefaultValue, isTouched } = field.state.meta
123126

124127
// The following line will re-create the non-Persistent `dirty` functionality.
125128
const nonPersistentIsDirty = !isDefaultValue

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

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -77,21 +77,51 @@ Each field has its own state, which includes its current value, validation statu
7777

7878
Example:
7979

80-
```tsx
80+
```ts
8181
const {
8282
value,
8383
meta: { errors, isValidating },
8484
} = field().state
8585
```
8686

87-
There are three field states can be very useful to see how the user interacts with a field. A field is _"touched"_ when the user clicks/tabs into it, _"pristine"_ until the user changes value in it, and _"dirty"_ after the value has been changed. You can check these states via the `isTouched`, `isPristine` and `isDirty` flags, as seen below.
87+
There are four states in the metadata that can be useful to see how the user interacts with a field:
8888

89-
```tsx
90-
const { isTouched, isPristine, isDirty } = field().state.meta
89+
- _"isTouched"_, after the user changes the field or blurs the field
90+
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
91+
- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
92+
- _"isBlurred"_, after the field has been blurred
93+
94+
```ts
95+
const { isTouched, isDirty, isPristine, isBlurred } = field().state.meta
9196
```
9297

9398
![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
9499

100+
## Understanding 'isDirty' in Different Libraries
101+
102+
Non-Persistent `dirty` state
103+
104+
- **Libraries**: React Hook Form (RHF), Formik, Final Form.
105+
- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again.
106+
107+
Persistent `dirty` state
108+
109+
- **Libraries**: Angular Form, Vue FormKit.
110+
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
111+
112+
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
113+
114+
- _"isDefaultValue"_, whether the field's current value is the default value
115+
116+
```ts
117+
const { isDefaultValue, isTouched } = field().state.meta
118+
119+
// The following line will re-create the non-Persistent `dirty` functionality.
120+
const nonPersistentIsDirty = !isDefaultValue
121+
```
122+
123+
![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png)
124+
95125
## Field API
96126

97127
The Field API is an object passed to the render prop function when creating a field. It provides methods for working with the field's state.

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

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,14 +83,44 @@ const {
8383
} = field.state
8484
```
8585

86-
There are three field states can be very useful to see how the user interacts with a field. A field is _"touched"_ when the user clicks/tabs into it, _"pristine"_ until the user changes value in it, and _"dirty"_ after the value has been changed. You can check these states via the `isTouched`, `isPristine` and `isDirty` flags, as seen below.
86+
There are four states in the metadata that can be useful to see how the user interacts with a field:
87+
88+
- _"isTouched"_, after the user changes the field or blurs the field
89+
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
90+
- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
91+
- _"isBlurred"_, after the field has been blurred
8792

8893
```ts
89-
const { isTouched, isPristine, isDirty } = field.state.meta
94+
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
9095
```
9196

9297
![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
9398

99+
## Understanding 'isDirty' in Different Libraries
100+
101+
Non-Persistent `dirty` state
102+
103+
- **Libraries**: React Hook Form (RHF), Formik, Final Form.
104+
- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again.
105+
106+
Persistent `dirty` state
107+
108+
- **Libraries**: Angular Form, Vue FormKit.
109+
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
110+
111+
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
112+
113+
- _"isDefaultValue"_, whether the field's current value is the default value
114+
115+
```ts
116+
const { isDefaultValue, isTouched } = field.state.meta
117+
118+
// The following line will re-create the non-Persistent `dirty` functionality.
119+
const nonPersistentIsDirty = !isDefaultValue
120+
```
121+
122+
![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png)
123+
94124
## Field API
95125

96126
The Field API is an object passed to the render prop function when creating a field. It provides methods for working with the field's state.

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

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -76,25 +76,55 @@ Example:
7676

7777
## Field State
7878

79-
Each field has its own state, which includes its current value, validation status, error messages, and other metadata. You can access a field's state using the `field.state` property.
79+
Each field has its own state, which includes its current value, validation status, error messages, and other metadata. You can access a field's state using the `field().state` property.
8080

8181
Example:
8282

83-
```js
83+
```ts
8484
const {
8585
value,
8686
meta: { errors, isValidating },
8787
} = field.state
8888
```
8989

90-
There are three field states can be very useful to see how the user interacts with a field. A field is _"touched"_ when the user clicks/tabs into it, _"pristine"_ until the user changes value in it, and _"dirty"_ after the value has been changed. You can check these states via the `isTouched`, `isPristine` and `isDirty` flags, as seen below.
90+
There are four states in the metadata that can be useful to see how the user interacts with a field:
9191

92-
```js
93-
const { isTouched, isPristine, isDirty } = field.state.meta
92+
- _"isTouched"_, after the user changes the field or blurs the field
93+
- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
94+
- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
95+
- _"isBlurred"_, after the field has been blurred
96+
97+
```ts
98+
const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
9499
```
95100

96101
![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
97102

103+
## Understanding 'isDirty' in Different Libraries
104+
105+
Non-Persistent `dirty` state
106+
107+
- **Libraries**: React Hook Form (RHF), Formik, Final Form.
108+
- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again.
109+
110+
Persistent `dirty` state
111+
112+
- **Libraries**: Angular Form, Vue FormKit.
113+
- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
114+
115+
We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
116+
117+
- _"isDefaultValue"_, whether the field's current value is the default value
118+
119+
```ts
120+
const { isDefaultValue, isTouched } = field.state.meta
121+
122+
// The following line will re-create the non-Persistent `dirty` functionality.
123+
const nonPersistentIsDirty = !isDefaultValue
124+
```
125+
126+
![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png)
127+
98128
## Field API
99129

100130
The Field API is an object provided by a scoped slot using the `v-slot` directive. This slot receives an argument named `field` that provides methods and properties for working with the field's state.

0 commit comments

Comments
 (0)