Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

FieldValidator.md

188 lines4.3 KB

1---
2id: FieldValidator
3title: FieldValidator
4---
5​
6Defined in: [validation.public.ts:983](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L983)
7​
8Configures validation of a field's value, optionally reacting to related fields.
9​
10## Extends
11​
12- [`Validator`](Validator.md)\<`TFormData`,
13 \| [`FieldValidatorFn`](../type-aliases/FieldValidatorFn.md)\<`TFormData`, `TFieldName`, `TFieldValue`\>
14 \| [`StandardSchemaV1`](../type-aliases/StandardSchemaV1.md)\<`TFieldValue`, `any`\>, `TFieldValue`, [`ConfigurableValidationTrigger`](../type-aliases/ConfigurableValidationTrigger.md), `"field"`\>
15​
16## Type Parameters
17​
18### TFormData
19​
20`TFormData`
21​
22Library-managed. Do not specify explicitly.
23​
24### TFieldName
25​
26`TFieldName`
27​
28Library-managed. Do not specify explicitly.
29​
30### TFieldValue
31​
32`TFieldValue`
33​
34Library-managed. Do not specify explicitly.
35​
36## Properties
37​
38### bailIfInvalid?
39​
40```ts
41optional bailIfInvalid?: boolean;
42```
43​
44Defined in: [validation.public.ts:29](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L29)
45​
46If `true`, skips this and subsequent validators when earlier validation has failed.
47​
48If `false`, earlier failures do not prevent this validator from running.
49​
50#### Default
51​
52```ts
53false
54```
55​
56#### Inherited from
57​
58[`Validator`](Validator.md).[`bailIfInvalid`](Validator.md#bailifinvalid)
59​
60***
61​
62### run
63​
64```ts
65run:
66 | FieldValidatorFn<TFormData, TFieldName, TFieldValue>
67| StandardSchemaV1<TFieldValue, any>;
68```
69​
70Defined in: [validation.public.ts:21](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L21)
71​
72The function or Standard Schema that validates the value in this validator's scope.
73​
74#### Inherited from
75​
76[`Validator`](Validator.md).[`run`](Validator.md#run)
77​
78***
79​
80### runOnMount?
81​
82```ts
83optional runOnMount?: boolean;
84```
85​
86Defined in: [validation.public.ts:64](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L64)
87​
88Whether this validator runs when the form is constructed or when its field
89or form group first mounts.
90​
91#### Default
92​
93```ts
94false
95```
96​
97#### Inherited from
98​
99[`Validator`](Validator.md).[`runOnMount`](Validator.md#runonmount)
100​
101***
102​
103### skipOnSubmit?
104​
105```ts
106optional skipOnSubmit?:
107 | boolean
108| ValidationPredicateFn<TFormData, TFieldValue, "field">;
109```
110​
111Defined in: [validation.public.ts:56](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L56)
112​
113Whether this validator runs during a submission attempt, independently of `triggers`.
114​
115Pass a boolean directly, or pass a function that returns
116`true` to skip it for the current attempt.
117​
118#### Default
119​
120```ts
121false
122```
123​
124#### Inherited from
125​
126[`Validator`](Validator.md).[`skipOnSubmit`](Validator.md#skiponsubmit)
127​
128***
129​
130### triggerDebounceMs?
131​
132```ts
133optional triggerDebounceMs?:
134 | number
135| ValidationDebounceFn<TFormData, TFieldValue, "field">;
136```
137​
138Defined in: [validation.public.ts:74](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L74)
139​
140The delay in milliseconds before validation runs for change or blur events.
141​
142Pass a number for a fixed delay, or pass a function that returns the delay
143for the current event. Repeated events restart the delay.
144Submission validation runs immediately.
145​
146#### Default
147​
148```ts
150```
151​
152#### Inherited from
153​
154[`Validator`](Validator.md).[`triggerDebounceMs`](Validator.md#triggerdebouncems)
155​
156***
157​
158### triggers
159​
160```ts
161triggers: ValidationTriggerOption<TFormData, TFieldValue, ConfigurableValidationTrigger, "field">[];
162```
163​
164Defined in: [validation.public.ts:82](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L82)
165​
166Change and blur events that can run this validator, optionally with conditions.
167​
168An empty array disables change and blur validation. Configure submission
169separately with `skipOnSubmit` and initial validation with `runOnMount`.
170​
171#### Inherited from
172​
173[`Validator`](Validator.md).[`triggers`](Validator.md#triggers)
174​
175***
176​
177### watchFields?
178​
179```ts
180optional watchFields?: DeepKeys<TFormData>[];
181```
182​
183Defined in: [validation.public.ts:1001](https://github.com/TanStack/form/blob/main/packages/form-core/src/validation.public.ts#L1001)
184​
185Other field paths whose change or blur events can run this validator.
186​
187Events must still match an enabled entry in `triggers`. The validator
188receives its own field's value, even when a watched field caused the event.