Skip to content

Commit c392c61

Browse files
crutchcorncrutchcorn
authored
docs: improve docs, add disclaimer where docs are outdated (#412)
1 parent 27dec1f commit c392c61

File tree

9 files changed

+2119
-559
lines changed

9 files changed

+2119
-559
lines changed

‎docs/guides/basic-concepts.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ title: Basic Concepts and Terminology
55

66
# Basic Concepts and Terminology
77

8+
> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
9+
810
This page introduces the basic concepts and terminology used in the @tanstack/react-form library. Familiarizing yourself with these concepts will help you better understand and work with the library.
911

1012
## Form Factory

‎docs/guides/important-defaults.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ id: important-defaults
33
title: Important Defaults
44
---
55

6+
> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
7+
68
Out of the box, TanStack Form is configured with **aggressive but sane** defaults. **Sometimes these defaults can catch new users off guard or make learning/debugging difficult if they are unknown by the user.** Keep them in mind as you continue to learn and use TanStack Form:
79

810
- Core

‎docs/installation.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,11 @@ id: installation
33
title: Installation
44
---
55

6-
TanStack Form is compatible with various front-end frameworks, including React, Solid, Svelte and Vue. To use TanStack Form with your desired framework, install the corresponding adapter via NPM
6+
While the core of TanStack Form is framework-agnostic and will be compatible with various front-end frameworks in the future, we only support React today.
7+
To use TanStack Form with React, install the adapter via NPM
78

89
```bash
910
$ npm i @tanstack/react-form
10-
# or
11-
$ pnpm add @tanstack/solid-form
12-
# or
13-
$ yarn add @tanstack/svelte-form
1411
```
1512

1613
> Depending on your environment, you might need to add polyfills. If you want to support older browsers, you need to transpile the library from `node_modules` yourselves.

‎docs/overview.md

Lines changed: 67 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -26,92 +26,103 @@ In the example below, you can see TanStack Form in action with the React framewo
2626
[Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-form/tree/main/examples/react/simple)
2727

2828
```tsx
29-
import React from 'react'
30-
import ReactDOM from 'react-dom/client'
31-
import { useForm, FieldApi } from '@tanstack/react-form'
29+
import React from "react";
30+
import ReactDOM from "react-dom/client";
31+
import { useForm } from "@tanstack/react-form";
32+
import type { FieldApi } from "@tanstack/react-form";
3233

3334
function FieldInfo({ field }: { field: FieldApi<any, any> }) {
3435
return (
3536
<>
3637
{field.state.meta.touchedError ? (
3738
<em>{field.state.meta.touchedError}</em>
38-
) : null}{' '}
39-
{field.state.meta.isValidating ? 'Validating...' : null}
39+
) : null}{" "}
40+
{field.state.meta.isValidating ? "Validating..." : null}
4041
</>
41-
)
42+
);
4243
}
4344

4445
export default function App() {
4546
const form = useForm({
4647
// Memoize your default values to prevent re-renders
4748
defaultValues: React.useMemo(
4849
() => ({
49-
firstName: '',
50-
lastName: '',
50+
firstName: "",
51+
lastName: "",
5152
}),
5253
[],
5354
),
5455
onSubmit: async (values) => {
5556
// Do something with form data
56-
console.log(values)
57+
console.log(values);
5758
},
58-
})
59+
});
5960

6061
return (
6162
<div>
6263
<h1>Simple Form Example</h1>
6364
{/* A pre-bound form component */}
64-
<form.Form>
65-
<div>
66-
{/* A type-safe and pre-bound field component*/}
67-
<form.Field
68-
name="firstName"
69-
validate={(value) => !value && 'A first name is required'}
70-
validateAsyncOn="change"
71-
validateAsyncDebounceMs={500}
72-
validateAsync={async (value) => {
73-
await new Promise((resolve) => setTimeout(resolve, 1000))
74-
return (
75-
value.includes('error') && 'No "error" allowed in first name'
76-
)
77-
}}
78-
children={(field) => (
79-
// Avoid hasty abstractions. Render props are great!
80-
<>
81-
<label htmlFor={field.name}>First Name:</label>
82-
<input name={field.name} {...field.getInputProps()} />
83-
<FieldInfo field={field} />
84-
</>
65+
<form.Provider>
66+
<form {...form.getFormProps()}>
67+
<div>
68+
{/* A type-safe and pre-bound field component*/}
69+
<form.Field
70+
name="firstName"
71+
onChange={(value) =>
72+
!value
73+
? "A first name is required"
74+
: value.length < 3
75+
? "First name must be at least 3 characters"
76+
: undefined
77+
}
78+
onChangeAsyncDebounceMs={500}
79+
onChangeAsync={async (value) => {
80+
await new Promise((resolve) => setTimeout(resolve, 1000));
81+
return (
82+
value.includes("error") && 'No "error" allowed in first name'
83+
);
84+
}}
85+
children={(field) => {
86+
// Avoid hasty abstractions. Render props are great!
87+
return (
88+
<>
89+
<label htmlFor={field.name}>First Name:</label>
90+
<input name={field.name} {...field.getInputProps()} />
91+
<FieldInfo field={field} />
92+
</>
93+
);
94+
}}
95+
/>
96+
</div>
97+
<div>
98+
<form.Field
99+
name="lastName"
100+
children={(field) => (
101+
<>
102+
<label htmlFor={field.name}>Last Name:</label>
103+
<input name={field.name} {...field.getInputProps()} />
104+
<FieldInfo field={field} />
105+
</>
106+
)}
107+
/>
108+
</div>
109+
<form.Subscribe
110+
selector={(state) => [state.canSubmit, state.isSubmitting]}
111+
children={([canSubmit, isSubmitting]) => (
112+
<button type="submit" disabled={!canSubmit}>
113+
{isSubmitting ? "..." : "Submit"}
114+
</button>
85115
)}
86116
/>
87-
</div>
88-
<div>
89-
<form.Field
90-
name="lastName"
91-
children={(field) => (
92-
<>
93-
<label htmlFor={field.name}>Last Name:</label>
94-
<input name={field.name} {...field.getInputProps()} />
95-
<FieldInfo field={field} />
96-
</>
97-
)}
98-
/>
99-
</div>
100-
<form.Subscribe
101-
selector={(state) => [state.canSubmit, state.isSubmitting]}
102-
children={([canSubmit, isSubmitting]) => (
103-
<button type="submit" disabled={!canSubmit}>
104-
{isSubmitting ? '...' : 'Submit'}
105-
</button>
106-
)}
107-
/>
108-
</form.Form>
117+
</form>
118+
</form.Provider>
109119
</div>
110-
)
120+
);
111121
}
112122

113-
const rootElement = document.getElementById('root')!
114-
ReactDOM.createRoot(rootElement).render(<App />)
123+
const rootElement = document.getElementById("root")!;
124+
125+
ReactDOM.createRoot(rootElement).render(<App />);
115126
```
116127

117128
## You talked me into it, so what now?

‎docs/reference/fieldApi.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ title: Field API
55

66
### Creating a new FieldApi Instance
77

8+
> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
9+
810
Normally, you will not need to create a new `FieldApi` instance directly. Instead, you will use a framework hook/function like `useField` or `createField` to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the `new FieldApi` constructor.
911

1012
```tsx

‎docs/reference/formApi.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ title: Form API
55

66
### Creating a new FormApi Instance
77

8+
> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
9+
810
Normally, you will not need to create a new `FormApi` instance directly. Instead, you will use a framework hook/function like `useForm` or `createForm` to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the `new FormApi` constructor.
911

1012
```tsx

‎examples/react/simple/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"preview": "vite preview"
99
},
1010
"dependencies": {
11-
"@tanstack/react-form": "0.0.11",
11+
"@tanstack/react-form": "0.0.12",
1212
"axios": "^0.26.1",
1313
"react": "^18.0.0",
1414
"react-dom": "^18.0.0",

0 commit comments

Comments
 (0)