Today, we cut the very first release of Formik v3 alpha. You can install it with:
The reason for this blog post is that there is a small breaking change that we unfortunately have no way of warning you about like we usually do with deprecation notices due to its nature.
But, before we get into the bad news, let's first share the good news:
The new alpha release contains new
formatOnBlur props for
useField(). These props make it a lot easier to implement input masking—a technique where you alter the format of the raw value of an input to make it appear in a certain way to the user (e.g. like a phone number (917) 555-1234 or a text-based date 10/2020). For you TypeScript friends here's what's new:
And here's a full example that uses the
format-string-by-pattern package to create various phone number input masks. Notice on the first input that even though you type 9999999999 the input's value (and Formik's internal value) is 999-999-9999. Neat!
Pro Tip: I'm all about making intuitive API's and so I'm aware that
format are hard to remember. The trick I've been using / saying in my head is as follows: "format" → sounds like "from" → "from Formik" → from Formik to input. Again, this is an alpha, so if it's too confusing, we'll rename these.
To support this new behavior, we needed to make a breaking change to the way that
onBlur handlers work when returned from
formikProps.getFieldProps(), which subsequently impacts
Field as well.
In the past, these
onBlur methods were identical to
formikProps.handleBlur (returned by
useFormik() or by the render prop
withFormik). However, as of 3.0.0-next.0, these methods behave differently, respectively.
When returned from
<Field>'s render prop,
onBlur are now already scoped to the given field and can now accept either a React Synthetic event or an arbitrary value. They no longer can be curried like
Here are some more concrete examples for you of what works and what doesn't work...
Still works, but does not support
No longer works
But instead you can just do this...
Normally, this small change wouldn't cause a major version bump, but because we no longer know if you are currying the
onChange method or are actually intending to set the string argument as a value we can't fire off a warning to save you from yourself. 🤷♂️
The primary goal of Formik v3 is to improve performance, ergonomics, and a11y, but also to recover from certain bets we made around React hooks that never happened (like context selectors). Unfortunately, to get where we want to go, there will be some more breaking changes and/or new components that will need to be introduced to the Formik family. The plan is to roll these out on the
next branch over the next few weeks, argue about naming for a bit, and then decide either to split some of the existing components into their own packages (a la
prop-types) and/or write codemods to automate the migration path. Either way, Formik is getting faster...A lot lot faster, which is something that's long overdue.