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

philosophy.md

51 lines2.8 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## Libraries are liberating
41​
42One of the main objectives of TanStack Form is that you should be wrapping it into your own component system or design system.
43​
44To support this, we have a number of utilities that make it easier to build your own components and customized hooks:
45​
46```ts
47// Exported from your own library with pre-bound components for your forms.
48export const { useAppForm } = createFormHook(/* options */)
49```
50​
51Without doing so, you're adding substantially more boilerplate to your apps and making your forms less consistent and user-friendly.