Styling React Applications with Ant.Design

Ant (GitHub) is much more than a React UI kit with a minimalist design aesthetic and every component under the sun. It is a rabbit’s hole that leads to a giant maze of interconnected libraries, with a serious ecosystem surrounding it. There’s a custom build tool based on Webpack called ant-tool, several CLI apps, community scaffolds, and a complete framework (dva, which has its own CLI as well). And the UI components are mini-projects in and of themselves — see this repo for information on each component.

Many of these libraries appear to be very polished, including an entire React animation library. And I’d love to learn more about them, but Ant comes with a challenge — the majority of the documentation is in Chinese.

How’s Your Chinese?

Let me preface this by pointing out that the components library and its terrific style guide have been translated into English by generous volunteers, so the UI kit is completely usable. And the translation effort demonstrates the project’s intentions to open up Ant to a wider audience, boding well for companies considering adopting it.

However, there are some language issues that remain. The English is sometimes confusing or obscure. The maintainer of the library has commented here that they welcome PRs for improving the documentation, so that could be a great way to get involved in this amazing project.

Good luck hunting down issues!

Another issue is that issues in Ant.Design are mostly filed and debated on GitHub in Chinese. This could be a deal breaker for enterprise applications, but I’m not sure it should be one for early startups since Ant can be used quite minimally, without making use of smarter features like built-in form validation. Still, if you find an issue or bug with the library, it will be difficult to research previous solutions to your issue, and that’s why I recommend making minimal use of the surrounding ecosystem at this stage.

Battle Tested

Popular UI libraries for React include Material-UI, Semantic-UI, Foundation, and Bootstrap (this and this), and they are all fairly mature. Material-UI should be singled out as it massively eclipses the others in popularity, with over 22k stargazers — and over 600 open issues. But it turns out that Ant.Design is a surprisingly worthy candidate as well. It’s battle tested by some of the most well-trodden sites on the web (Alibaba, Baidu), and it boasts a brilliant style guide, custom tooling, and, of course, a comprehensive catalogue of components. It also has only 85 open issues at the time of writing, which is a good thing considering its popularity.

So let’s take a tour of the library, see what it has to offer, and how to get started using it.

Ant Components

The Ant components list is dizzying. Sure, it contains the basics — modals, forms (inline and vertical), navigation menus, a grid system. But it also contains a ton of extras, such as a @mentioning system, a timeline, badges, a seriously nice table system, and other small fancy features, such as an involved address box (see the Habitual Residence field). Have a look — it has everything that a modern web application should, with a tasteful, minimalist aesthetic.

Design Principles

There’s a nice, concise section in the documentation on the guiding principles of Ant.Design. I found it a great read as it got me thinking a lot about UI/UX considerations, especially the “Provide an Invitation” section, where they discuss different ways of making interactions discoverable by a user. By the way, if anyone can recommend me a good book on UX, I would be grateful.

Grid System

The Ant layout system is comprised of a 24-aliquot (a great new word that I learned from the translated documentation — it means parts of a whole) grid and a separate Layout component than you can choose to use. The grid uses the familiar Row/Col system, but you can also specify a prop called flex which allows you to harness Flexbox properties to define a responsive UI. (See a previous blog post of mine for help grokking the Flex standard.)

Flexbox is now fully supported on just about every browser (with partial support on IE 11 as well as some older mobile browsers), so it should be fine to use. If your customer base is largely Internet Explorer users, which does happen in some industries or countries, you would be wise to abstain from using flex Rows or the Layout component, as Layout is built strictly on Flexbox.

Layout includes components for a Sider, Header, Content, and Footer. Again, these are strictly based on Flexbox, so there’s no choice here — but to be honest I’m not sure what these components give you on top of using the standard Row/Col grid system, aside from a couple extra props you can make use of and possibly some built-in design choices. All in all, it doesn’t seem to me to be hugely useful.

Grid Props

Col elements can be supplied with a span prop to define how many aliquots a column takes up and an offset prop to define an optional offset; Row can take a gutter prop to define space between columns in a row (in pixels, not aliquots).

Here’s a UI example from a side project of mine. It contains one row with two columns:

The code would look something like this:

Forms

Ant does not let you down as far as forms are concerned, with options for inline, horizontal, and vertical forms, amazing select boxes, and clear validation messages and icons. In fact, it goes a little overboard here. It allows you to wrap your entire form-rendering component in a higher-order component à la Form.create()(<Component />) to gain access to a built-in validator syntax and custom two-way-binding system (cue audible lip biting). You can then specify standard rules such as ‘required’, or supply custom validator methods. (What are Higher Order Components? Check out this excellent post by James K. Nelson.)

Do you need to use their HOC? Absolutely not, and I’m not sure you should. As I said above, going down that path could expose you to language risk should you encounter bugs and I don’t see why you would want to use a custom two-way binding data system anyway. But you could easily use the HOC and just not use the two-way data binding.

Au Naturel — Plain React Forms

So let’s go over how to use the Ant validation messages without using their higher-order component.

Ant gives us three props that we can supply to each Form.Item component to display validation messages or icons:

1. validateStatus — This determines the colour & icon scheme of the validation message (see photo above) — valid options are success, warning, error, and validating.
2. help — The validation message to display.
3. hasFeedback — This is one of them props that don’t require a value. Just include if you want to display the associated icon, and it defaults to true.

Prettiest validations that I’ve ever seen.

Here’s an example of a simple form element that displays a validation message:

Notice that I used the long-form Form.Item component name. You can make yourself a shortcut for this and any other Ant sub-components as follows:

const FormItem = Form.Item;
// .. allows you to use:
<FormItem />

Form Validation using the Ant Higher-Order Component

Now what if we do want to make use of the Ant Form decorator? It’s fairly straightforward to implement. Create your React component class, and then pass it as an argument to Form.create(). The component can then be exported:

class SomeComponent extends React.Component {
  render() {<place_form_here.. />}
}  
FancyFormComponent = Form.create()(SomeComponent);
export { FancyFormComponent as default };  // imported as SomeComponent

Inside your form, decorate your Input fields using the getFieldDecorater method, which exposes a ton of extra props on your component. You can now manipulate form elements directly from the props (eek!).

This example in the documentation gives a thorough demonstration on using the complete higher-order component.

Interactive Components — Message (Alert)

Ant provides a number of other components that give web applications a high degree of interactivity. A great example is alerts — or messages, as they’re called in Ant. Adding an alert is as simple as calling message.success('Great! Item has been saved.') in your component. Message types include success, warning, or error. Just don’t forget to import message (lowercase) from ‘antd’.

Minimalism at its Best

Installing Ant.Design

As I mentioned above, you can either go all-in on the Ant ecosystem (with its custom Webpack adapter), or just opt for the design framework. I went with the latter and I suspect you might too, not the least because using other parts of the ecosystem could require a working knowledge of Chinese. But I’ll cover both options.

Option 1 — Use the CLI

Ant comes with antd-init, a CLI for generating a complete React application with Ant installed. I do not recommend this route for non-Chinese speakers, but if you want to try it, getting started is easy. Just install the CLI using npm, create a new folder, and run antd-init:

npm install antd-init -g; mkdir demo-app; cd $_; antd-init;

You will then be greeted by the following message:

antd-init@2 is only for experience antd. If you want to create projects, it’s better to init with dva-cli. dva is a redux and react based application framework. elm concept, support side effects, hmr, dynamic load and so on.`

It’s a rabbit’s hole. Open your new application and you will see that your familiar webpack.config.js file is no longer familiar — the CLI uses ant-tool, a “Build Tool Based on Webpack” that I mentioned above. The documentation is in Chinese, but it appears to set common defaults for Webpack and then allow you to just supply values that you want to override. Here’s what the config file looks like:

// Learn more on how to config.
// — https://github.com/ant-tool/atool-build#配置扩展
module.exports = function(webpackConfig) {
 webpackConfig.babel.plugins.push(‘transform-runtime’);
 webpackConfig.babel.plugins.push([‘import’, {
 libraryName: ‘antd’,
 style: ‘css’,
 }]);
 return webpackConfig;
};

The index.js contains a lovely demo page that uses the understated Ant styling.

Option 2 — Use Standard Webpack

This would be my preferred route, but it can be more complicated getting your Webpack settings right at first. The Getting Started page includes some good instructions. First install Ant in your React app:

$ npm install antd --save

Ant recommends using their own babel-plugin-import in your .babelrc:

"presets": [
    "react",
    ...
  ],
  "plugins": ["transform-decorators-legacy", ..., ["import", [{ libraryName: "antd", style: "css" }]]
  ]
}

Make sure your Webpack includes loaders for .js and .css files, and you should be good to go. To use an Ant component, import it in the module file. E.g.

import { Row, Col, Icon, Button } from 'antd';

Conclusion

There’s no doubt that Ant has a lot to offer as a UI framework, with a formidable catalogue of components and a serious ecosystem around it. It does, however, come with some risk. If you experience an issue with the library, you may be stuck communicating in Chinese. Ultimately I recommend trying it out if you like the minimalist aesthetic, while keeping usage of the peripheral Ant ecosystem to a minimum.