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

philosophy.md

78 lines3.5 KB

1---
2id: philosophy
3title: Philosophy
4---
5​
6Every well-established project should have a philosophy that guides its development. Without a core philosophy, development can languish in endless decision-making and have weaker APIs as a result.
7​
8This document outlines the core principles that drive the development and feature-set of TanStack Form.
9​
10## Upgrading unified APIs
11​
12APIs come with tradeoffs. As a result, it can be tempting to make each set of tradeoffs available to the user through different APIs. However, this can lead to a fragmented API that is harder to learn and use.
13​
14While this may mean a higher learning curve, it means that you don't have to question which API to use internally or have higher cognitive overhead when switching between APIs.
15​
16## Forms need flexibility
17​
18TanStack Form is designed to be flexible and customizable. While many forms may conform to similar patterns, there are always exceptions; especially when forms are a core component of your application.
19​
20As a result, TanStack Form supports multiple methods for validation:
21​
22- **Timing customizations**: You can validate on blur, change, submit, or even on mount.
23- **Validation strategies**: You can validate on individual fields, the entire form, or a subset of fields.
24- **Custom validation logic**: You can write your own validation logic or use a library like [Zod](https://zod.dev/) or [Valibot](https://valibot.dev/).
25- **Custom error messages**: You can customize the error messages for each field by returning any object from a validator.
26- **Async validation**: You can validate fields asynchronously and have common utils like debouncing and cancellation handled for you.
27​
28## Controlled is Cool
29​
30In a world where controlled vs. uncontrolled inputs are a hot topic, TanStack Form is firmly in the controlled camp.
31​
32This comes with a number of advantages:
33​
34- **Predictable**: You can predict the state of your form at any point in time.
35- **Easier testing**: You can easily test your forms by passing in values and asserting on the output.
36- **Non-DOM support**: You can use TanStack Form with React Native, Three.js framework adapters, or any other framework renderer.
37- **Enhanced conditional logic**: You can easily conditionally show/hide fields based on the form state.
38- **Debugging**: You can easily log the form state to the console to debug issues.
39​
40## Generics are grim
41​
42You should never need to pass a generic or use an internal type when leveraging TanStack Form. This is because we've designed the library to infer everything from runtime defaults.
43​
44When writing sufficiently correct TanStack Form code, you should not be able to distinguish between JavaScript usage and TypeScript usage, with the exception of any type casts you might do of runtime values.
45​
46Instead of:
47​
48```ts
49useForm<MyForm>()
50```
51​
52You should do:
53​
54```ts
55interface Person {
56 name: string
57 age: number
59​
60const defaultPerson: Person = { name: 'Bill Luo', age: 24 }
61​
62useForm({
63 defaultValues: defaultPerson,
64})
65```
66​
67## Libraries are liberating
68​
69One of the main objectives of TanStack Form is that you should be wrapping it into your own component system or design system.
70​
71To support this, we have a number of utilities that make it easier to build your own components and customized hooks:
72​
73```ts
74// Exported from your own library with pre-bound components for your forms.
75export const { useAppForm, withForm } = createFormHook(/* options */)
76```
77​
78Without doing so, you're adding substantially more boilerplate to your apps and making your forms less consistent and user-friendly.