Managing forms in a Meteor/React project with the uniforms package
This is a guest blog post from Maciek Stasiełuk, software architect at Vazco.eu, a Meteor-focused software house based in Poland and the UK that’s always trying to stay on the bleeding edge.
If you’ve created a more complex React app before, then you know that managing forms can be a really tedious task. We may have a solution for that! In this article, we’ll introduce a new package we’ve built to more easily manage forms in Meteor/React apps, take you through the steps to create a simple form with it, and share a bit about how we built it.
Why yet another form package?
At Vazco, we’ve been using Meteor for almost four years. About two years ago we decided to replace Blaze with React for all new projects. During the transition we stumbled upon a problem: there was no good alternative to AutoForm in React. Sure, there were some React components to build forms, or a few community efforts to recreate AutoForm using React, but none of them was good enough for us.
This is where uniforms come in — we decided to build a package that would be easy to use in simple scenarios and powerful enough to support even complex cases.
Radosław Miernik lead the project and created not only a great package but also a wonderful community around it. As a result, uniforms is now in the top 10 popular React forms packages on GitHub, with over 200 stars and 4000 downloads per month in npm.
What does`uniforms` offer?
At the high level,uniforms is a set of React libraries for building forms. It was created with Meteor in mind but doesn’t depend on it, so you can use it in any React app.
Out of the box, uniforms lets you:
- Auto-generate forms based on a given schema
- Use popular CSS frameworks thanks to the wide range of themes
- Easily tweak form layouts to better fit with your UI
- Create custom fields with just one line
- Validate forms inline and asynchronously
uniforms is built in a modular way, as a set of packages. The core uniforms package is the heart of everything and contains logic to handle schemas, validation and processing.
Support for GraphQL, SimpleSchema v.1 and v.2 is built in, but you can use any schema — all you have to do is to write a small wrapper around it.
To render forms, you’ll also need a theme package. There are out-of-the-box themes for popular CSS frameworks (AntD, Bootstrap3, Bootstrap4, Material UI and Semantic UI) or you can use a plain HTML theme and style it however you like. If you want, you can also create new themes to better suit your needs; it’s fairly easy. Some of the popular themes are created and maintained by the community.
Let’s create a simple form
In this example, I’ll assume that you already have a working Meteor app using React as a frontend (if not, please see this example app).
To use uniforms, you need to add select packages to the project. I’ll use Semantic, but it could be any theme, or the unstyled version for plain HTML.
meteor npm install --save uniforms
meteor npm install --save uniforms-semantic # or any other theme
This example will make use of SimpleSchema (a very popular schema in Meteor community), but remember that it could be any supported schema, including GraphQL.
When you have a schema (and you usually already have them in your project anyway) all you have to do is to render the form. The simplest, yet very powerful, way is to use the AutoForm component from uniforms:
This will cover rendering all fields from your schema (based on the type in the schema), validation etc. As a result you’ll get something like this:
Of course, you have full control over how the form is rendered.
Let’s say you want to change layout and order of the fields (mixing it with other custom components in the process), use longer input for the content and show status as radio buttons, rather than a select.
You can do it right in your React component, without touching the schema:
The result is a more customized form:
Right now all that’s left to do is call your backend with either Meteor.call, a GraphQL mutation or any other way that’s comfortable.
If you’re interested, the snippets above come from an example app.
You’re welcome to clone it and play with it yourself.
Online playground with live preview
You can also try uniforms online demo playground, where you can mix’n’match schemas, themes and different settings to view live results right in your browser.
Simply go to uniforms.tools and fiddle around.
Under the hood
There are few interesting things about how uniforms was built.
The codebase is organized in a multi-package repository managed by Lerna, so that the core and all the themes are released in sync, and we’re treating semantic versioning seriously. It’s also worth mentioning that all the packages have 100% test coverage.
There’s also a very interesting class-based inheritance concept for forms. Basically, there are a few types of forms with different capabilities. Most of the time you’ll be using either AutoForm or ValidatedForm, but there are quite a few more to choose from:
So what’s so special about it? I think that Radek, the author of the concept, will explain it better:
If you are not familiar with concept of HOC, read one of many posts about them first.
I’m sure you’ve read at least one of Why ES6 classes are bad or class considered harmful posts. I’ve read them too, so why is uniforms using classes? Well, it’s all about the complexity.
I wanted to achieve the same functionality as with multiple HOCs, but within one component. To be honest, readability is more important than performance. In short, I’ve reached (more or less) traits with ES6 clasess. The result?
While it’s not a universal approach that will work in every situation, using it in uniforms allows us to deliver clean-looking components while keeping extendability and separation of concerns.
Plans for the future
At Vazco we’re using uniforms in all our production apps, so it’s not going away anytime soon. We received a warm reception from the community, and a few companies aside from us have already already adopted it (not counting individual developers).
Radosław Miernik is working on the project making it better every day.
You can check the roadmap on GitHub. I can give you a sneak peek that a version 2.0 is coming soon. It will be almost 100% backward compatible, so you don’t have to worry about breaking changes. The most notable feature will be a performance boost at the cost of the support for older React versions.
Try uniforms out for yourself and let us know what you think!
Managing forms in a Meteor/React project with uniforms was originally published in Meteor Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.