diff --git a/docs/assets/field-states-extended.png b/docs/assets/field-states-extended.png index 033fe6e68..1ecc677af 100644 Binary files a/docs/assets/field-states-extended.png and b/docs/assets/field-states-extended.png differ diff --git a/docs/assets/field-states.png b/docs/assets/field-states.png index a78ed16f9..869f41f5c 100644 Binary files a/docs/assets/field-states.png and b/docs/assets/field-states.png differ diff --git a/docs/framework/angular/guides/basic-concepts.md b/docs/framework/angular/guides/basic-concepts.md index 0b4ca9836..75f1f82a9 100644 --- a/docs/framework/angular/guides/basic-concepts.md +++ b/docs/framework/angular/guides/basic-concepts.md @@ -40,21 +40,51 @@ Each field has its own state, which includes its current value, validation statu Example: -```tsx +```ts const { value, meta: { errors, isValidating }, } = field.state ``` -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. +There are four states in the metadata that can be useful to see how the user interacts with a field: -```tsx -const { isTouched, isPristine, isDirty } = field.state.meta +- _"isTouched"_, after the user changes the field or blurs the field +- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of _"isPristine"_ +- _"isPristine"_, until the user changes the field value. Opposite of _"isDirty"_ +- _"isBlurred"_, after the field has been blurred + +```ts +const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta ``` ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png) +## Understanding 'isDirty' in Different Libraries + +Non-Persistent `dirty` state + +- **Libraries**: React Hook Form (RHF), Formik, Final Form. +- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again. + +Persistent `dirty` state + +- **Libraries**: Angular Form, Vue FormKit. +- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value. + +We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag: + +- _"isDefaultValue"_, whether the field's current value is the default value + +```ts +const { isDefaultValue, isTouched } = field.state.meta + +// The following line will re-create the non-Persistent `dirty` functionality. +const nonPersistentIsDirty = !isDefaultValue +``` + +![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png) + ## Field API 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. diff --git a/docs/framework/lit/guides/basic-concepts.md b/docs/framework/lit/guides/basic-concepts.md index a67352d3b..efc3a7c60 100644 --- a/docs/framework/lit/guides/basic-concepts.md +++ b/docs/framework/lit/guides/basic-concepts.md @@ -86,17 +86,47 @@ For Example: 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. -```tsx +```ts const { value, meta: { errors, isValidating }, } = field.state ``` -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. +There are four states in the metadata that can be useful to see how the user interacts with a field: -```tsx -const { isTouched, isPristine, isDirty } = field.state.meta +- _"isTouched"_, after the user changes the field or blurs the field +- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine` +- _"isPristine"_, until the user changes the field value. Opposite of `isDirty` +- _"isBlurred"_, after the field has been blurred + +```ts +const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta ``` ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png) + +## Understanding 'isDirty' in Different Libraries + +Non-Persistent `dirty` state + +- **Libraries**: React Hook Form (RHF), Formik, Final Form. +- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again. + +Persistent `dirty` state + +- **Libraries**: Angular Form, Vue FormKit. +- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value. + +We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag: + +- _"isDefaultValue"_, whether the field's current value is the default value + +```ts +const { isDefaultValue, isTouched } = field.state.meta + +// The following line will re-create the non-Persistent `dirty` functionality. +const nonPersistentIsDirty = !isDefaultValue +``` + +![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png) diff --git a/docs/framework/react/guides/basic-concepts.md b/docs/framework/react/guides/basic-concepts.md index 67cdc8776..d3ef30619 100644 --- a/docs/framework/react/guides/basic-concepts.md +++ b/docs/framework/react/guides/basic-concepts.md @@ -85,21 +85,22 @@ Each field has its own state, which includes its current value, validation statu Example: -```tsx +```ts const { value, meta: { errors, isValidating }, } = field.state ``` -There are three states in the metadata that can be useful to see how the user interacts with a field: +There are four states in the metadata that can be useful to see how the user interacts with a field: -- _"isTouched"_, after the user clicks/tabs into the field -- _"isPristine"_, until the user changes the field value -- _"isDirty"_, after the fields value has been changed +- _"isTouched"_, after the user changes the field or blurs the field +- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine` +- _"isPristine"_, until the user changes the field value. Opposite of `isDirty` +- _"isBlurred"_, after the field has been blurred -```tsx -const { isTouched, isPristine, isDirty } = field.state.meta +```ts +const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta ``` ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png) @@ -116,10 +117,12 @@ Persistent `dirty` state - **Libraries**: Angular Form, Vue FormKit. - **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value. -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. +We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag: -```tsx -const { isTouched, isPristine, isDirty, isDefaultValue } = field.state.meta +- _"isDefaultValue"_, whether the field's current value is the default value + +```ts +const { isDefaultValue, isTouched } = field.state.meta // The following line will re-create the non-Persistent `dirty` functionality. const nonPersistentIsDirty = !isDefaultValue diff --git a/docs/framework/solid/guides/basic-concepts.md b/docs/framework/solid/guides/basic-concepts.md index c6fdfba35..3f96cc0a8 100644 --- a/docs/framework/solid/guides/basic-concepts.md +++ b/docs/framework/solid/guides/basic-concepts.md @@ -77,21 +77,51 @@ Each field has its own state, which includes its current value, validation statu Example: -```tsx +```ts const { value, meta: { errors, isValidating }, } = field().state ``` -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. +There are four states in the metadata that can be useful to see how the user interacts with a field: -```tsx -const { isTouched, isPristine, isDirty } = field().state.meta +- _"isTouched"_, after the user changes the field or blurs the field +- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine` +- _"isPristine"_, until the user changes the field value. Opposite of `isDirty` +- _"isBlurred"_, after the field has been blurred + +```ts +const { isTouched, isDirty, isPristine, isBlurred } = field().state.meta ``` ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png) +## Understanding 'isDirty' in Different Libraries + +Non-Persistent `dirty` state + +- **Libraries**: React Hook Form (RHF), Formik, Final Form. +- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again. + +Persistent `dirty` state + +- **Libraries**: Angular Form, Vue FormKit. +- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value. + +We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag: + +- _"isDefaultValue"_, whether the field's current value is the default value + +```ts +const { isDefaultValue, isTouched } = field().state.meta + +// The following line will re-create the non-Persistent `dirty` functionality. +const nonPersistentIsDirty = !isDefaultValue +``` + +![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png) + ## Field API 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. diff --git a/docs/framework/svelte/guides/basic-concepts.md b/docs/framework/svelte/guides/basic-concepts.md index 266861af3..1037068a3 100644 --- a/docs/framework/svelte/guides/basic-concepts.md +++ b/docs/framework/svelte/guides/basic-concepts.md @@ -83,14 +83,44 @@ const { } = field.state ``` -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. +There are four states in the metadata that can be useful to see how the user interacts with a field: + +- _"isTouched"_, after the user changes the field or blurs the field +- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine` +- _"isPristine"_, until the user changes the field value. Opposite of `isDirty` +- _"isBlurred"_, after the field has been blurred ```ts -const { isTouched, isPristine, isDirty } = field.state.meta +const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta ``` ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png) +## Understanding 'isDirty' in Different Libraries + +Non-Persistent `dirty` state + +- **Libraries**: React Hook Form (RHF), Formik, Final Form. +- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again. + +Persistent `dirty` state + +- **Libraries**: Angular Form, Vue FormKit. +- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value. + +We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag: + +- _"isDefaultValue"_, whether the field's current value is the default value + +```ts +const { isDefaultValue, isTouched } = field.state.meta + +// The following line will re-create the non-Persistent `dirty` functionality. +const nonPersistentIsDirty = !isDefaultValue +``` + +![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png) + ## Field API 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. diff --git a/docs/framework/vue/guides/basic-concepts.md b/docs/framework/vue/guides/basic-concepts.md index a8b97999a..979c39727 100644 --- a/docs/framework/vue/guides/basic-concepts.md +++ b/docs/framework/vue/guides/basic-concepts.md @@ -76,25 +76,55 @@ Example: ## Field State -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. +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. Example: -```js +```ts const { value, meta: { errors, isValidating }, } = field.state ``` -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. +There are four states in the metadata that can be useful to see how the user interacts with a field: -```js -const { isTouched, isPristine, isDirty } = field.state.meta +- _"isTouched"_, after the user changes the field or blurs the field +- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine` +- _"isPristine"_, until the user changes the field value. Opposite of `isDirty` +- _"isBlurred"_, after the field has been blurred + +```ts +const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta ``` ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png) +## Understanding 'isDirty' in Different Libraries + +Non-Persistent `dirty` state + +- **Libraries**: React Hook Form (RHF), Formik, Final Form. +- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again. + +Persistent `dirty` state + +- **Libraries**: Angular Form, Vue FormKit. +- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value. + +We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag: + +- _"isDefaultValue"_, whether the field's current value is the default value + +```ts +const { isDefaultValue, isTouched } = field.state.meta + +// The following line will re-create the non-Persistent `dirty` functionality. +const nonPersistentIsDirty = !isDefaultValue +``` + +![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png) + ## Field API 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.