diff --git a/docs/api/fieldarray.md b/docs/api/fieldarray.md index 6e7124dd0..99ebf64da 100644 --- a/docs/api/fieldarray.md +++ b/docs/api/fieldarray.md @@ -67,7 +67,7 @@ export const FriendList = () => ( ### `name: string` -The name or path to the relevant key in [`values`]. +The name or path to the relevant key in [`values`](api/formik.md#values-field-string-any). ### `validateOnChange?: boolean` @@ -109,7 +109,7 @@ You can also iterate through an array of objects, by following a convention of ` Validation can be tricky with ``. -If you use [`validationSchema`] and your form has array validation requirements (like a min length) as well as nested array field requirements, displaying errors can be tricky. Formik/Yup will show validation errors inside out. For example, +If you use [`validationSchema`](api/formik.md#validationschema-schema-schema) and your form has array validation requirements (like a min length) as well as nested array field requirements, displaying errors can be tricky. Formik/Yup will show validation errors inside out. For example, ```js const schema = Yup.object().shape({ diff --git a/docs/api/formik.md b/docs/api/formik.md index ee0940b74..8204a6381 100644 --- a/docs/api/formik.md +++ b/docs/api/formik.md @@ -98,11 +98,11 @@ to `` #### `handleSubmit: (e: React.FormEvent) => void` -Submit handler. This should be passed to `
...
`. To learn more about the submission process, see [How Form Submission Works](#how-form-submission-works). +Submit handler. This should be passed to `
...
`. To learn more about the submission process, see [Form Submission](guides/form-submission.md). #### `isSubmitting: boolean` -Submitting state of the form. Returns `true` if submission is in progress and `false` otherwise. IMPORTANT: Formik will set this to `true` as soon as submission is _attempted_. To learn more about the submission process, see [How Form Submission Works](#how-form-submission-works). +Submitting state of the form. Returns `true` if submission is in progress and `false` otherwise. IMPORTANT: Formik will set this to `true` as soon as submission is _attempted_. To learn more about the submission process, see [Form Submission](guides/form-submission.md). #### `isValid: boolean` @@ -111,7 +111,7 @@ Returns `true` if the there are no `errors`, or the result of #### `isValidating: boolean` -Returns `true` if Formik is running any validation function, `false` otherwise. To learn more about what happens with `isValidating` during the submission process, see [How Form Submission Works](#how-form-submission-works). +Returns `true` if Formik is running any validation function, `false` otherwise. To learn more about what happens with `isValidating` during the submission process, see [Form Submission](guides/form-submission.md). #### `resetForm: (nextValues?: Values) => void` @@ -140,8 +140,8 @@ Trigger a form submission. #### `submitCount: number` -Number of times user tried to submit the form. Increases when `handleSubmit`(#handlesubmit-values-values-formikbag-formikbag--void) is called, resets after calling -`handleReset`(#handlereset---void). `submitCount` is readonly computed property and should not be mutated directly. +Number of times user tried to submit the form. Increases when [`handleSubmit`](#handlesubmit-e-reactformevent-htmlformevent-void) is called, resets after calling +[`handleReset`](#handlereset-void). `submitCount` is readonly computed property and should not be mutated directly. #### `setFieldValue: (field: string, value: any, shouldValidate?: boolean) => void` @@ -173,7 +173,7 @@ otherwise be expressed/stored with other methods. This is useful for capturing and passing through API responses to your inner component. `status` should only be modifed by calling -`setStatus: (status?: any) => void`(#setstatus-status-any--void) +[`setStatus`](#setstatus-status-any-void). #### `touched: { [field: string]: boolean }` diff --git a/docs/api/withFormik.md b/docs/api/withFormik.md index 21c03cd3f..0f4d94910 100644 --- a/docs/api/withFormik.md +++ b/docs/api/withFormik.md @@ -133,4 +133,4 @@ component's `errors`. Its keys should match those of `values`. ## Injected props and methods -These are identical to the props of [` ...} />`](formik#formik-render-methods-and-props) +These are identical to the props of [` ...} />`](api/formik.md#formik-render-methods-and-props) diff --git a/docs/overview.md b/docs/overview.md index 56dc682e8..bd7d6e62c 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -221,9 +221,11 @@ API that's pretty similar [Joi](https://github.com/hapijs/joi) / [React PropTypes](https://github.com/facebook/prop-types) but is small enough for the browser and fast enough for runtime usage. Because I :heart: Yup sooo much, Formik has a special config option / prop for Yup called -[`validationSchema`] which will automatically transform Yup's validation errors -into a pretty object whose keys match [`values`] and [`touched`]. Anyways, you -can install Yup from npm... +[`validationSchema`](api/formik.md#validationschema-schema-schema) which will +automatically transform Yup's validation errors into a pretty object whose keys +match [`values`](api/formik.md#values-field-string-any) and +[`touched`](api/formik.md#touched-field-string-boolean). Anyways, you can +install Yup from npm... ``` npm install yup --save diff --git a/website/pages/en/versions.js b/website/pages/en/versions.js index e8339bd89..bc93bf419 100644 --- a/website/pages/en/versions.js +++ b/website/pages/en/versions.js @@ -35,7 +35,9 @@ function Versions() { {latestVersion} - Documentation + + Documentation + Release Notes @@ -72,7 +74,11 @@ function Versions() { {version} - Documentation + + Documentation + diff --git a/website/versioned_docs/version-1.2.0/api/fieldarray.md b/website/versioned_docs/version-1.2.0/api/fieldarray.md index 605c141ec..55f443c56 100644 --- a/website/versioned_docs/version-1.2.0/api/fieldarray.md +++ b/website/versioned_docs/version-1.2.0/api/fieldarray.md @@ -68,7 +68,7 @@ export const FriendList = () => ( ### `name: string` -The name or path to the relevant key in [`values`]. +The name or path to the relevant key in [`values`](api/formik.md#values-field-string-any). ### `validateOnChange?: boolean` @@ -110,7 +110,7 @@ You can also iterate through an array of objects, by following a convention of ` Validation can be tricky with ``. -If you use [`validationSchema`] and your form has array validation requirements (like a min length) as well as nested array field requirements, displaying errors can be tricky. Formik/Yup will show validation errors inside out. For example, +If you use [`validationSchema`](api/formik.md#validationschema-schema-schema) and your form has array validation requirements (like a min length) as well as nested array field requirements, displaying errors can be tricky. Formik/Yup will show validation errors inside out. For example, ```js const schema = Yup.object().shape({ @@ -183,6 +183,7 @@ The following methods are made available via render props. * `unshift: (value: any) => number`: Add an element to the beginning of an array and return its length * `remove(index: number): T | undefined`: Remove an element at an index of an array and return it * `pop(): T | undefined`: Remove and return value from the end of the array +* `replace: (index: number, value: any) => void`: Replace a value at the given index into the array ## FieldArray render methods diff --git a/website/versioned_docs/version-1.2.0/api/formik.md b/website/versioned_docs/version-1.2.0/api/formik.md index 2996fab20..321d07dc9 100644 --- a/website/versioned_docs/version-1.2.0/api/formik.md +++ b/website/versioned_docs/version-1.2.0/api/formik.md @@ -99,11 +99,11 @@ to `` #### `handleSubmit: (e: React.FormEvent) => void` -Submit handler. This should be passed to `
...
`. To learn more about the submission process, see [How Form Submission Works](#how-form-submission-works). +Submit handler. This should be passed to `
...
`. To learn more about the submission process, see [Form Submission](guides/form-submission.md). #### `isSubmitting: boolean` -Submitting state of the form. Returns `true` if submission is in progress and `false` otherwise. IMPORTANT: Formik will set this to `true` as soon as submission is _attempted_. To learn more about the submission process, see [How Form Submission Works](#how-form-submission-works). +Submitting state of the form. Returns `true` if submission is in progress and `false` otherwise. IMPORTANT: Formik will set this to `true` as soon as submission is _attempted_. To learn more about the submission process, see [Form Submission](guides/form-submission.md). #### `isValid: boolean` @@ -112,7 +112,7 @@ Returns `true` if the there are no `errors`, or the result of #### `isValidating: boolean` -Returns `true` if Formik is running any validation function, `false` otherwise. To learn more about what happens with `isValidating` during the submission process, see [How Form Submission Works](#how-form-submission-works). +Returns `true` if Formik is running any validation function, `false` otherwise. To learn more about what happens with `isValidating` during the submission process, see [Form Submission](guides/form-submission.md). #### `resetForm: (nextValues?: Values) => void` @@ -141,8 +141,8 @@ Trigger a form submission. #### `submitCount: number` -Number of times user tried to submit the form. Increases when `handleSubmit`(#handlesubmit-values-values-formikbag-formikbag--void) is called, resets after calling -`handleReset`(#handlereset---void). `submitCount` is readonly computed property and should not be mutated directly. +Number of times user tried to submit the form. Increases when [`handleSubmit`](#handlesubmit-e-reactformevent-htmlformevent-void) is called, resets after calling +[`handleReset`](#handlereset-void). `submitCount` is readonly computed property and should not be mutated directly. #### `setFieldValue: (field: string, value: any, shouldValidate?: boolean) => void` @@ -174,7 +174,7 @@ otherwise be expressed/stored with other methods. This is useful for capturing and passing through API responses to your inner component. `status` should only be modifed by calling -`setStatus: (status?: any) => void`(#setstatus-status-any--void) +[`setStatus`](#setstatus-status-any-void). #### `touched: { [field: string]: boolean }` diff --git a/website/versioned_docs/version-1.2.0/api/withFormik.md b/website/versioned_docs/version-1.2.0/api/withFormik.md index 1299d252a..508a45a9a 100644 --- a/website/versioned_docs/version-1.2.0/api/withFormik.md +++ b/website/versioned_docs/version-1.2.0/api/withFormik.md @@ -134,4 +134,4 @@ component's `errors`. Its keys should match those of `values`. ## Injected props and methods -These are identical to the props of [` ...} />`](formik#formik-render-methods-and-props) +These are identical to the props of [` ...} />`](api/formik.md#formik-render-methods-and-props) diff --git a/website/versioned_docs/version-1.2.0/guides/react-native.md b/website/versioned_docs/version-1.2.0/guides/react-native.md index b72b495cd..4b9b67153 100644 --- a/website/versioned_docs/version-1.2.0/guides/react-native.md +++ b/website/versioned_docs/version-1.2.0/guides/react-native.md @@ -45,4 +45,4 @@ DOM and React Native are: 1. Formik's `props.handleSubmit` is passed to a ` + + )} + + +); + +export default Basic; +``` + +### Reducing boilerplate + +The code above is very explicit about exactly what Formik is doing.`onChange` -> `handleChange`, `onBlur` -> `handleBlur`, and so on. However, to save you time, Formik comes with a few extra components to make life easier and less verbose: `
`, ``, and ``. They use React context to hook into the parent `` state/methods. + +```jsx +// Render Prop +import React from 'react'; +import { Formik, Form, Field } from 'formik'; + +const Basic = () => ( +
+

Any place in your app!

+ { + let errors = {}; + if (!values.email) { + errors.email = 'Required'; + } else if ( + !/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(values.email) + ) { + errors.email = 'Invalid email address'; + } + return errors; + }} + onSubmit={(values, { setSubmitting }) => { + setTimeout(() => { + alert(JSON.stringify(values, null, 2)); + setSubmitting(false); + }, 400); + }} + > + {({ isSubmitting }) => ( + + + + + + + + )} + +
+); + +export default Basic; +``` + +### Complementary Packages + +As you can see above, validation is left up to you. Feel free to write your own +validators or use a 3rd party library. Personally, I use +[Yup](https://github.com/jquense/yup) for object schema validation. It has an +API that's pretty similar [Joi](https://github.com/hapijs/joi) / +[React PropTypes](https://github.com/facebook/prop-types) but is small enough +for the browser and fast enough for runtime usage. Because I :heart: Yup sooo +much, Formik has a special config option / prop for Yup called +[`validationSchema`](api/formik.md#validationschema-schema-schema) which will +automatically transform Yup's validation errors into a pretty object whose keys +match [`values`](api/formik.md#values-field-string-any) and +[`touched`](api/formik.md#touched-field-string-boolean). Anyways, you can +install Yup from npm... + +``` +npm install yup --save +```