In the last few months I’ve been working a lot with forms. I had to do a large refactoring in one of AUTO1’s applications, and through all the research, I also encountered the term subform. The concept was troublesome not only for me.\nI found more than one issue on the Formik repository about developers asking for help.\nIn this article I'll try to clarify this concept and show you how to use it properly.
\nIf you’ve ever worked on a medium-large project with a reasonable amount of forms, you might have probably noticed that you could potentially reuse a lot of fields, sometimes even entire forms!\nThat’s the core of the subform concept: reusable components (fields or group of fields) that can be composed together to create bigger forms.
\nAt the beginning I had a lot of questions in my mind like:
\nThese questions and many others appeared while I was refactoring existing codebase. Many similar questions created by other developers appeared in the Formik repository as issues.
\nDon’t get me wrong: implementing scalable validation for a single form is not that hard. The complicated thing is to keep validation and state flexible while you write your subforms. What does it mean? We’ll see that in a moment.
\nFormik is an amazing library, one of the bests for this job, and here’s what it brings to the table:
\nFormik provides a Field component that, thanks to the React Context API, will be automatically connected to the Form component that wraps our Field, regardless of how deep our Field is in the tree.
\nYup is a library to create validation schemas. This library is very similar to the prop-types of React, so it is very simple to start using it.\nFormik supports Yup natively, so you just need to define the schema and pass it to Formik, it will take care of the rest.
\nSo this is how Formik will make our life easier not only while creating subforms but also when we’ll need to maintain them!
\nLet’s create our first subform! Before we start, we need to clarify what our subform will be responsible for:
\nIn our case, we're going to create a form that allows to create a new user.\nWe'll need to display the following fields:
\nJust keep it simple. So, let’s create our NewUserSubForm directory and our fieldsNames file. It’s just a file that exports constants, don’t worry. It will look like this:
// UserSubform/fieldsNames.js\nexport const FIRST_NAME = 'firstName'\nexport const LAST_NAME = 'lastName'\nexport const EMAIL = 'email'\nexport const PASSWORD = 'password'// UserSubform/validationSchema.js\nimport * as yup from 'yup'\nimport { FIRST_NAME, LAST_NAME, EMAIL, PASSWORD } from './fieldsNames'\n\nconst MIN_PASSWORD_LENGTH = 8\n\nconst REQUIRED_MESSAGE = 'This field is required'\nconst INVALID_EMAIL_FORMAT = 'Invalid email format'\nconst PASSWORD_TOO_SHOWRT = `The password must be at least ${MIN_PASSWORD_LENGTH} characters long`\n\nexport default yup.object({\n [FIRST_NAME]: yup.string().required(REQUIRED_MESSAGE),\n [LAST_NAME]: yup.string().required(REQUIRED_MESSAGE),\n [EMAIL]: yup\n .string()\n .required(REQUIRED_MESSAGE)\n .email(INVALID_EMAIL_FORMAT),\n [PASSWORD]: yup\n .string()\n .required(REQUIRED_MESSAGE)\n .min(MIN_PASSWORD_LENGTH, PASSWORD_TOO_SHOWRT),\n})We’ve just defined our validation schema regardless the markup of our form. This file just contains all the validation logic and has one responsibility. If in the future we’ll need to add some more validation options, we’ll just need to change it here.
\nNow it’s time for the default values. Initial values are required from Formik because it uses controlled inputs. So, if you don’t specify those values, you’ll get and error from React as soon as you try to change the content of the input.
\n// UserSubform/defaultValues.js\nimport { FIRST_NAME, LAST_NAME, EMAIL, PASSWORD } from './fieldsNames'\n\nexport default {\n [FIRST_NAME]: '',\n [LAST_NAME]: '',\n [EMAIL]: '',\n [PASSWORD]: '',\n}And now the master piece: The React component. Remember: we just need to use the Fields and not the Formik or the Form components.
\n// UserSubform/index.js\nimport React, { Fragment } from 'react'\nimport { Field, ErrorMessage } from 'formik'\nimport { FIRST_NAME, LAST_NAME, EMAIL, PASSWORD } from './fieldsNames'\n\nexport default class NewUserSubForm extends React.Component {\n render() {\n return (\n <Fragment>\n <Field component=\"input\" name={FIRST_NAME} />\n <ErrorMessage name={FIRST_NAME} />\n <Field component=\"input\" name={LAST_NAME} />\n <ErrorMessage name={LAST_NAME} />\n <Field component=\"input\" name={EMAIL} />\n <ErrorMessage name={EMAIL} />\n <Field component=\"input\" name={PASSWORD} />\n <ErrorMessage name={PASSWORD} />\n </Fragment>\n )\n }\n}And that’s it. In this phase we can test every single part of our subform: validation, the default values schema and the React component.
\nA piece of advice: Formik sets the fields’ values in its state using the name property, but the cool thing is that it uses it like the Lodash set function. It means that we can write the name of a field like this: user.firstName. In this way Formik will create an object in its state called user, and then a property inside of user called firstName that will contain the value of our field.
This mechanism gives us power to improve the flexibility of our subform. How?
\nLet’s edit our component in a way that it will accept an optional property called namespace. If received, the component will prepend the namespace to every field name. In this way it will be easier to wrap all the subform’s values under a certain object in the main form.
// UserSubform/index.js\nimport React, { Fragment } from 'react'\nimport PropTypes from 'prop-types'\nimport { Field, ErrorMessage } from 'formik'\nimport { FIRST_NAME, LAST_NAME, EMAIL, PASSWORD } from './fieldsNames'\n\nexport default class NewUserSubForm extends React.Component {\n static propTypes = {\n namespace: PropTypes.string,\n }\n\n withNamespace(fieldName) {\n const { namespace } = this.props\n\n return namespace ? `${namespace}.${fieldName}` : fieldName\n }\n\n render() {\n const { withNamespace } = this\n\n return (\n <Fragment>\n <Field component=\"input\" name={withNamespace(FIRST_NAME)} />\n <ErrorMessage name={withNamespace(FIRST_NAME)} />\n <Field component=\"input\" name={withNamespace(LAST_NAME)} />\n <ErrorMessage name={withNamespace(FIRST_NAME)} />\n <Field component=\"input\" name={withNamespace(EMAIL)} />\n <ErrorMessage name={withNamespace(FIRST_NAME)} />\n <Field component=\"input\" name={withNamespace(PASSWORD)} />\n <ErrorMessage name={withNamespace(FIRST_NAME)} />\n </Fragment>\n )\n }\n}We don’t need to do that with the other parts of the subform, the main form will be responsible for that. And, about the main form, let’s see how to implement it!
\nFinally, we’re going to create our main form component. Let’s define its responsibilities just like we did with our subform. The main form will be responsible for:
\nIt's a lot of responsibilities, and that’s all right. The main form represents a specific point in the UI/UX where the user needs to insert some data. In our case, it could be a registration form, but it could also be a registration combined with a purchase, just like when you buy something from amazon and you agree to sign up in the process.
\nThe point is: A Form is a unique component that represent a specific use case, so it has to be designed accordingly. That’s why it makes no sense to create a “god-form” component with hundreds of props that decides which endpoint the form is going to use. It just creates useless complexity.
\nIn my opinion, the best way to organize this approach is to create a folder where you’ll store all your subforms. Every subform will be represented by its directory and it will contain all its parts: validation, values, fields and the React component.\nA main form, instead, should be created ad-hoc to fit the needs of a certain use case, for example inside a certain route.
\nSo, with that in mind, let’s proceed to the implementation. We’ll have our directory called registrationForm and it will have the same parts of a subform:
Fields Names
\n// CreateNewUserRoute/form/fieldsNames.js\nexport { FIRST_NAME, LAST_NAME, EMAIL, PASSWORD } from './subforms/NewUserSubForm/fieldsNames'\nexport const USER = 'user'Validation
\n// CreateNewUserRoute/form/validationSchema.js\nimport * as yup from 'yup'\nimport { USER } from './fieldsNames'\nimport userValidationSchema from './subforms/NewUserSubForm/validationSchema'\n\nexport default yup.object({\n [USER]: userValidationSchema,\n})Default values
\n// CreateNewUserRoute/form/defaultValues.js\nimport { USER } from './field Names'\nimport userDefaultValues from './subforms/NewUserSubForm/defaultValues'\n\nexport default {\n [USER]: userDefaultValues,\n}The React component
\n// CreateNewUserRoute/form/index.js\nimport React from 'react'\nimport { Formik, Form } from 'formik'\nimport NewUserSubForm from './subforms/NewUserSubForm'\nimport validationSchema from './validationSchema'\nimport defaultValues from './defaultValues'\nimport { USER } from './fieldsNames'\nimport ErrorBanner from 'path/to/components/ErrorBanner'\n\nexport default class NewUserSubForm extends React.Component {\n state = {\n unknownErrors: null,\n }\n\n onSubmit = async (values, { setSubmitting, setErrors }) => {\n try {\n // Send values somehow\n await sendForm(values)\n } catch (e) {\n // Map and show the errors in your form\n const [formErrors, unknownErrors] = mapErrorsFromRequest(e)\n\n setErrors(formErrors)\n this.setState({\n unknownErrors,\n })\n } finally {\n setSubmitting(false)\n }\n }\n\n render() {\n const { unknownErrors } = this.state\n\n return (\n <Formik onSubmit={this.onSubmit} initialValues={defaultValues} validationSchema={validationSchema}>\n {() => (\n <Form>\n {unknownErrors && <ErrorBanner errors={unknownErrors} />}\n <NewUserSubForm namespace={USER} />\n </Form>\n )}\n </Formik>\n )\n }\n}And that’s it! Of course, this is a very simple example, you could have different needs.
\nI want to leave you with some advices that helped me while I was refactoring my codebase. It's good to have them in mind to ease the process of code refactoring.
\nA subform should have only first level values in its state, which means that, when you design a subform, you shouldn’t get crazy about the shape of its values. It should be a flat object and every key should contain the field value.\nThis way it’s so much easier to write validations, default values and error handling (and why not, also the React component).
\nYou can avoid this advice only when you are using a subform into you subform. For example, let’s say you have an address subform. It has a lot of fields and a complex validation schema. In that scenario all the logic will be handled by the address subform and you’ll just need to orchestrate it in your own subform, just like you would do in the main form.
\nI didn’t do it in this article but the idea is to export a function instead of a schema. This function will accept parameters that will define the schema that you’ll get.\nIn this case you can toggle the “required” validation in some cases, or other kinds of validation.
\nExample: let’s say that we want to make the “lastName” field optional, but not always. That’s how you could define your schema:
\n// UserSubform/validationSchema.js\nimport * as yup from 'yup'\nimport { FIRST_NAME, LAST_NAME, EMAIL, PASSWORD } from './fieldsNames'\n\nconst MIN_PASSWORD_LENGTH = 8\n\nconst REQUIRED_MESSAGE = 'This field is required'\nconst INVALID_EMAIL_FORMAT = 'Invalid email format'\nconst PASSWORD_TOO_SHOWRT = `The password must be long at least ${MIN_PASSWORD_LENGTH} characters`\n\nexport default function validationSchema(mandatoryFields = { [LAST_NAME]: true }) {\n return yup.object({\n [FIRST_NAME]: yup.string().required(REQUIRED_MESSAGE),\n [LAST_NAME]: yup.lazy(() => (mandatoryFields.lastName ? yup.string().required(REQUIRED_MESSAGE) : yup.string())),\n [EMAIL]: yup\n .string()\n .required(REQUIRED_MESSAGE)\n .email(INVALID_EMAIL_FORMAT),\n [PASSWORD]: yup\n .string()\n .required(REQUIRED_MESSAGE)\n .min(MIN_PASSWORD_LENGTH, PASSWORD_TOO_SHOWRT),\n })\n}Now you have a scalable validation schema.\nIn this way you can always decide if a certain field is required or not. Also, you can extend that function to add parameters. In this way, if your subform scales, you’ll just need to add parameters and adjust the code in the subform accordingly, but every single form that uses your subform won’t be affected by these changes because everything is retro compatible.
\nDealing with forms is not easy. Of course, there are simple cases, but there are also trickier ones. This was my way to organize the code, and of course, it’s not perfect.\nI’m sure there are other thousands amazing ways to solve this problem better than this, but for now, this is the best way I’ve found to keep everything testable, maintainable and scalable.
\nI hope this will help you, and if you have a better approach, I’m looking forward to reading it!\nUntil next time, happy hacking!
","fields":{"slug":"/the-concept-of-subforms-with-formik/","tags":["formik","forms","react","subforms"]}}}]}},"pageContext":{"slug":"/tags/formik","tag":"formik","categories":["Architecture","Coding","DevOps","Engineering","ProjectManagement","QA","Social","TechRadar"]}}