How to customize ant design with React & Webpack — the missing guide

Note: this guide is only for Ant Design 2.x.

Ant Design has an amazing set of react components. If you are reading this, then I don’t need to explain why or how to use them but how to customize them.

The official docs only give you some clues into customization but not a full how-to guide. The intent of this write-up is to guide you through the initial setup for customizing the default ant-d theme.

The TL;DR or “just let me see the code” can be found here.

*Readers — please comment on the original post if you see any errors or submit pull requests. The idea is to keep this write up, up-to-date and as accurate possible (m̶a̶y̶b̶e̶ ̶e̶v̶e̶n̶ ̶m̶e̶r̶g̶e̶d̶ ̶i̶n̶t̶o̶ ̶t̶h̶e̶ ̶d̶o̶c̶s̶ —  update 2017–06–25, added to docs).

*Update 2017–11–03 — I apologize for not being able to answer all the questions coming in. Due to the myriad of ways to config a react app it’s difficult to provide any support in the comment section. Please try to run the demo repo I put together and submit pull requests or file bugs there. Thanks!

Step One- Install Packages:

• Install Ant Design:

npm install antd --save

• Install Ant’s (poorly named) modular plugin loader:

This will allow us to bundle only the ant components we use.

npm install babel-plugin-import --save-dev

• Install the less-vars-to-js package:

Takes in the contents of a less file as a string and returns an object containing all the variables it found.

npm install less-vars-to-js --save-dev

• Install less and webpack css/less loaders if you have not already:

npm install less less-loader css-loader style-loader --save-dev

Step Two — Configure Babel-loader:

Add babel-plugin-import to the webpack babel loader or use a .babelrc file.

//.babelrc
{ 
  "presets: [...]
  "plugins": [
    ["import", {"libraryName": "antd", "style": true} ],
    ...
  ]
}

// webpack2.config.js
module: {
  rules: [
    {
      loader: 'babel-loader',
      exclude: /node_modules/,
      test: /\.js$/,
      options: {
        presets: [...]
        plugins: [
          ['import', { libraryName: "antd", style: true }]
        ]
      },
    },
    ...
  ]
}

// webpack1.config.js
module: {
  loaders: [
    {
      test: /\.jsx?$/,
      exclude: /node_modules/,
      loader: 'babel', 
      query: {
        plugins: [
          ['import', { libraryName: "antd", style: true }]
        ]
      }
    },
  ...
  ]
}

Step Three — Create a .less file for the ant theme variable overrides:

// ant-default-vars.less
// Available theme variables can be found in
// https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less

@primary-color: #193D71; <-- our first ant theme override!

Step four— Configure webpack less-loader:

// webpack*.config.js
const path = require('path');
const fs  = require('fs');

const lessToJs = require('less-vars-to-js');
const themeVariables = lessToJs(fs.readFileSync(path.join(__dirname, './ant-theme-vars.less'), 'utf8'));
...

// webpack2.config.js
module: {
  rules: [
    ...
    {
      test: /\.less$/,
      use: [
        {loader: "style-loader"},
        {loader: "css-loader"},
        {loader: "less-loader",
          options: {
            modifyVars: themeVariables
          }
        }
      ]
    }
  ]
}

//webpack1.config.js
module: {
  loaders: [
    {
      test: /\.less$/,
      loader: 'style-loader!css-loader!less-loader',
      query: {
        modifyVars: themeVariables
      }
    },
  ...
  ]
}

Step Five (optional)  —  configure fonts:

Fonts/icons are served from the Alibaba CDN by default. You can download and serve them from your project or add them to your own CDN (recommended). Below shows how to configure the URL that they are served from.

// webpack*.config.js
const path = require('path');
const fs  = require('fs');

const lessToJs = require('less-vars-to-js');
const themeVariables = lessToJs(fs.readFileSync(path.join(__dirname, './ant-theme-vars.less'), 'utf8'));

// lessToJs does not support @icon-url: "some-string", so we are manually adding it to the produced themeVariables js object here
themeVariables["@icon-url"] = "'//localhost:8080/fonts/iconfont'";

That’s It!

Hopefully this helps those who have been stuck or confused when trying to customize the ant-d library.

Caveats

• You can only override what is in ant’s default.less file.
• If you need to modify the theme outside of ant’s default.less you have to find the class(es) and manually override them in your projects css :(
• Theme overrides are done at compile time, so no (built-in) theme-switching during runtime.

This post originally appeared on Medium.