Neptune Web is published to npm as two packages: @transferwise/components and @transferwise/neptune-css.

If you want to use the components, you need Neptune CSS.

# yarn
yarn add @transferwise/components @transferwise/neptune-css
yarn add react react-dom prop-types currency-flags # peer dependencies

# npm
npm install @transferwise/components @transferwise/neptune-css
npm install react react-dom prop-types currency-flags # peer dependencies

Note: Peer dependencies are only necessary if you're using components. currency-flags is only required if you're using the Money Input or if you're using flags on the Select.


// This line only needs to be imported once in your application
import '@transferwise/neptune-css/dist/css/neptune.css';

import { Button } from '@transferwise/components';

export default function Hello() {
  return (
    <Button size={Button.Size.SMALL} block={true}>
      Hello Neptune

For information on what classes are available, see the styles documentation. Refer to components for usage documentation, live previews and code snippets for each component.

By default, apps come polyfilled. If you would like to use an unpolyfilled version because your app provides its own polyfills, see Advanced Components Usage below.


Neptune CSS exposes a number of of useful CSS properties on :root. You can find information about what is available in the tokens documentation. If you're not familiar with using custom properties, have a read of the documentation on MDN.

import '@transferwise/neptune-css/dist/css/neptune.css';
.my-button {
  background-color: var(--color-primary);
  border-radius: var(--border-radius);
  border: 1px solid transparent;

  color: #fff;
  cursor: pointer;

  padding: var(--space-8);

Advanced CSS Usage

We expose three bundles for use. Our neptune.css bundle has everything. This is what you should use if using components. If you aren't using components, you have the option of just using Core, or Core + Addons. Follow the links for full documentation on what is available in each bundle.

Note: there are other files in the dist folder other than those mentioned here. Please do not rely on them, as we may remove them in future releases.

Core includes the tokens, as well as typography styles.Addons provide a number of utility classes for display, spacing and more.
// Everything
import '@transferwise/neptune-css/dist/css/neptune.css';

// Core (includes tokens)
import '@transferwise/neptune-css/dist/css/neptune-core.css';

// Addons
import '@transferwise/neptune-css/dist/css/neptune-addons.css';

Advanced Components Usage

The components are exposed in two formats: UMD and ES. We also provide polyfilled and non-polyfilled versions.

Which bundle should I use?

UMD is a combination of CommonJS and AMD. It works in both browser and server environments (Node). ES uses the standardized ES module format.

If you are using a bundler that supports ES module imports, you can use the ES build. If not, you will need the UMD build.

Because we declare standard main and module properties in our package.json file, if you are happy to use the polyfilled version it's likely that you will get the right import for your environment.

"main": "./build/umd/polyfill/main.js",
"module": "./build/es/polyfill/index.js",

We expose polyfilled versions by default, to ensure we meet our Browser Support policy. If your application already includes polyfills, you can optimise your bundle by including non-polyfilled versions of the components.

Below is a comparison of the different bundle options, along with where you can access them.

BundleDefaultSizeTreeshakingExtra setup required
UMD + polyfill384.125 Kb (gzip:~117.399 Kb)None.
UMD343.31 Kb (gzip:~100.283 Kb)You must override the default import and include your own polyfill.
ES + polyfill280.218 KbNone.
ES271.295 KbYou must override the default import and include your own polyfill.

If you need to override the import to use a different bundle, here is where you can find the different combinations.

UMD + polyfill
ES + polyfill

You will need to find out how to specify module overrides in your particular build environment. Here's an example of how to do it in Webpack:

  resolve: {
    alias: {
      '@transferwise/components': require.resolve(


By default when importing this - import { Button, Upload } from "@transferwise/components"; - you will get polyfilled UMD if your bundler doesn't support tree-shaking, polyfilled ES if it does.

Edit these docs on Github