Simpler getting started

Author: CodeStix

articles/Getting-started.md

@@ -17,9 +17,7 @@ This library works with both **Javascript** and **Typescript**. Typescript is ce
 
 ### Using the `useForm` hook
 
-A form always starts with the `useForm` hook call, this function returns a form state manager ([FormState](/docs/FormState)), which you must then pass to all your inputs (this is required for type-checking).
-
-All of the form hook ([`useForm`](/docs/useForm), [`useChildForm`](/docs/useChildForm) ...) must be called, unconditionally, at the start of your component, just like the normal React hooks.
+A form always starts with the `useForm` hook call, this function returns a form state manager ([FormState](/docs/FormState)), which you must then pass to all your inputs.
 
 ✔️ **Importing and using `useForm`**
 
@@ -34,8 +32,7 @@ function MyForm() {
 
 ### Creating the submit handler
 
-Pass `form.handleSubmit` to the form's `onSubmit` prop to validate before calling your callback function.
-You can also just use a `<button>` and submitting in the button's `onClick` handler, but this event does not fire when pressing return/enter in a text input!
+Use `form.handleSubmit` to validate before calling your function. It does not get called if there is a validation error, and prevents the page from reloading.
 
 ✔️ **`<form>` element with `onSubmit` event**
 
@@ -44,37 +41,31 @@ import { useForm } from "typed-react-form";
 
 function MyForm() {
     const form = useForm({ email: "" });
+
+    function submit() {
+        // The form.handleSubmit validates the form before calling this function
+        console.log("submit", form.values);
+    }
+
     // Use the standard html form element, which exposes the onSubmit event.
     return (
-        <form
-            onSubmit={form.handleSubmit(() => {
-                // The form.handleSubmit validates the form before calling your callback
-                // Do your submit logic here...
-                console.log("submit", form.values);
-            })}
-        >
+        <form onSubmit={form.handleSubmit(submit)}>
             {/* Make sure to add type="submit" */}
             <button type="submit">Submit!</button>
         </form>
     );
 }
 ```
 
-`form.handleSubmit()` just returns a helper function that wraps `ev.preventDefault()`, `form.validate()` and `form.setState()`.
-
 ### Creating inputs
 
-This library is build upon the fact that only the things that change should rerender (~refresh), for example: when the _name_ field changes, only the inputs that use the _name_ field will rerender.
-
-The built-in form elements ([`FormInput`](/docs/FormInput), [`FormSelect`](/docs/FormSelect) ...) implement this by listening for changes only on their specified field. You can also use multiple inputs on the same field (they will the synchronized) and listen for changes on a field by using the [`useListener`](/docs/useListener) hook or [`Listener`](/docs/Listener) component.
-
-You are now ready to create inputs, this library provides the following built-in components to create type-checked inputs:
+This library provides the following built-in components to create type-checked inputs:
 
 -   [FormInput](/docs/FormInput)
 -   [FormSelect](/docs/FormSelect)
 -   [FormTextArea](/docs/FormTextArea)
 
-**When these inputs do not satisfy your needs**, you can always [create your own](/docs/Custom-inputs#example-custom-input). These built-in components are just abstractions around hook calls.
+When these inputs do not satisfy your needs, you can always [implement your own](/docs/Custom-inputs#example-custom-input). These built-in components are just abstractions around hook calls.
 
 ✔️ **Example type-checked form consisting of 2 fields**
 
@@ -84,17 +75,18 @@ import { useForm, FormInput } from "typed-react-form";
 
 function MyForm() {
     const form = useForm({ email: "", password: "" });
+
+    async function submit() {
+        // Implement your submit logic here...
+        console.log("submitting", form.values);
+        // Fake fetch, by waiting for 500ms
+        await new Promise((res) => setTimeout(res, 500));
+        // Optional: set new default values
+        form.setDefaultValues(form.values);
+    }
+
     return (
-        <form
-            onSubmit={form.handleSubmit(async (ev) => {
-                // Implement your submit logic here...
-                console.log("submitting", form.values);
-                // Fake fetch, by waiting for 500ms
-                await new Promise((res) => setTimeout(res, 500));
-                // Optional: set new default values
-                form.setDefaultValues(form.values);
-            })}
-        >
+        <form onSubmit={form.handleSubmit(submit)}>
             {/* Make sure to pass the form prop! */}
             <FormInput form={form} name="email" type="text" />
             <FormInput form={form} name="password" type="password" />
@@ -104,11 +96,6 @@ function MyForm() {
 }
 ```
 
-**When you have an object or array field**, you need to _unwrap_ this field by using a child/array form. When _unwrapped_ you can use the inputs above.
-
--   [Object fields](/docs/Object-fields)
--   [Array fields](/docs/Array-fields)
-
 ## Step 3: It's your turn
 
 Tweak the above example to your desire by...

articles/useAnyListener.md

@@ -4,6 +4,8 @@ Because this library does not rerender the whole form component when a field cha
 
 The useAnyListener hook listens for any change on a form. Behaves a lot like [`useListener`](/docs/useListener) but does not take a `name` parameter.
 
+This hook must be called, unconditionally, at the start of your component, just like the normal React hooks.
+
 **To listen to just one field** instead of every field, use the `useListener` hook instead.
 
 **Use the [`AnyListener` component](/docs/AnyListener) if you want to use these hooks without creating a new component each time.**

articles/useArrayForm.md

@@ -2,6 +2,8 @@
 
 A hook that provides array manipulation functions and optimizations for an array field. This is the array-optimized version of [`useChildform`](/docs/useChildForm). This hook only causes a rerender when the array size changes (this is why `values.map((e) => ...)` works when adding/removing a value).
 
+This hook must be called, unconditionally, at the start of your component, just like the normal React hooks.
+
 **If your array field can/will be null or undefined**, you should use the [`ArrayForm`](/docs/ArrayForm) component instead, which does not render when the array is null/undefined.
 
 `useArrayForm(parentForm, nameOfArrayField)`

articles/useChildForm.md

@@ -2,6 +2,8 @@
 
 Creates a form based on another form's field. Use this with nested objects. This hook does not cause a rerender.
 
+This hook must be called, unconditionally, at the start of your component, just like the normal React hooks.
+
 **If your field can/will be null or undefined**, you should use the [`ChildForm`](/docs/ChildForm) component instead, which does not render when the field is null/undefined.
 
 `useChildForm(parentForm, name)`

articles/useForm.md

@@ -2,6 +2,8 @@
 
 Creates a new form state manager. This hook does not cause a rerender.
 
+This hook must be called, unconditionally, at the start of your component, just like the normal React hooks.
+
 **Note for using `setState` along with `useForm`**: This library is built upon the fact that only the things that change should rerender. When using `setState` with the form, a state change causes the whole form to rerender. You can reduce this problem by creating components from the things that use the state, or you can use [custom form state](/docs/useForm#defaultstate-optional-issubmitting-false).
 
 `useForm(defaultValues, validator?, validateOnChange = false, validateOnMount = false, defaultState = {isSubmitting: false})`

articles/useListener.md

@@ -1,10 +1,14 @@
 # `useListener`
 
-Because this library does not rerender the whole form component when a field changes, there must be a way to get notified about state changes. This is where listeners come in.
+This library is build upon the fact that only the things that change should rerender, for example: when the _name_ field changes, only the inputs that use the _name_ field will rerender.
+
+The built-in form elements ([`FormInput`](/docs/FormInput), [`FormSelect`](/docs/FormSelect) ...) implement this by listening for changes only on their specified field. You can also use multiple inputs on the same field (they will the synchronized).
 
 The useListener hook listens for changes on a specific form field. It behaves like useState. Because this hooks causes a rerender, you **shouldn't** use
 this hook in the same component as the form it is using (causes the whole form to rerender). You **should** always create a new component which contains the hook and use that. Or use the [`Listener`](/docs/Listener) component, which wraps the `useListener` hook for you.
 
+This hook must be called, unconditionally, at the start of your component, just like the normal React hooks.
+
 **To listen for all form fields at once**, use the [`useAnyListener`](/docs/useAnyListener) hook instead.
 
 **✔️ Right usage**

pages/docs/test.tsx

@@ -13,14 +13,15 @@ import {
 
 function MyForm() {
     const form = useForm({ email: "" });
+
+    function submit() {
+        // The form.handleSubmit validates the form before calling this function
+        console.log("submit", form.values);
+    }
+
     // Use the standard html form element, which exposes the onSubmit event.
     return (
-        <form
-            onSubmit={form.handleSubmit(() => {
-                // The form.handleSubmit validates the form before calling your callback
-                console.log("submit", form.values);
-            })}
-        >
+        <form onSubmit={form.handleSubmit(submit)}>
             {/* Make sure to add type="submit" */}
             <button type="submit">Submit!</button>
         </form>
@@ -29,17 +30,18 @@ function MyForm() {
 
 function MyForm2() {
     const form = useForm({ email: "", password: "" });
+
+    async function submit() {
+        // Implement your submit logic here...
+        console.log("submitting", form.values);
+        // Fake fetch, by waiting for 500ms
+        await new Promise((res) => setTimeout(res, 500));
+        // Optional: set new default values
+        form.setDefaultValues(form.values);
+    }
+
     return (
-        <form
-            onSubmit={form.handleSubmit(async (ev) => {
-                // Implement your submit logic here...
-                console.log("submitting", form.values);
-                // Fake fetch, by waiting for 500ms
-                await new Promise((res) => setTimeout(res, 500));
-                // Optional: set new default values
-                form.setDefaultValues(form.values);
-            })}
-        >
+        <form onSubmit={form.handleSubmit(submit)}>
             {/* Make sure to pass the form prop! */}
             <FormInput form={form} name="email" type="text" />
             <FormInput form={form} name="password" type="password" />