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 and Icons.

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

# npm
npm install @transferwise/components @transferwise/neptune-css @transferwise/icons
npm install react react-dom react-intl 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.


// These CSS imports only need to be imported once in your application
import '@transferwise/neptune-css/dist/css/neptune.css';
import '@transferwise/icons/lib/styles/main.min.css';

// This is only necessary if you are using the UMD build
import '@transferwise/components/build/main.css';

import { Provider, Button } from '@transferwise/components';
import componentsTranslations from '@transferwise/components/build/i18n';

import appTranslations from '...';

export default function App() {
  const locale = ...
  const messages = { ...componentsTranslations[locale], ...appTranslations[locale] };
  return (
    // Components must be wrapped by the Provider component, which initialises and provides
    // context data for them. This should usually be done once at the top app level component
    <Provider i18n={{ locale, messages }}>
      <Button size={Button.Size.SMALL} block>...</Button>

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.

Translations and the Provider

You need to pass a translations object to the Provider component. This can be done in a few different ways, depending on the setup of your library / application.

Note: Provider component uses react-intl which creates a context using RawIntlProvider. If your code already uses react-intl and its providers (e.g RawIntlProvider or IntlProvider) replace them with Provider passing all translations objects (@transferwise/components translation files, your app translation files, etc) there (Translations can be combined using rest operator (as shown on above example) or using formatjs compile). In case your code uses some other framework / library then setup should be handled separately, example with retranslate library:

import { TranslationProvider } from 'retranslate';
import appTranslations from '...';

import { Provider } from '@transferwise/components';
import componentsTranslations from '@transferwise/components/build/i18n';

const locale = '...';

const App = () => (
  <TranslationProvider messages={appTranslations} language={locale}>
    <Provider i18n={{ locale, messages: componentsTranslations }}>

Translation files can be accessed directly, which gives you the opportunity to load them dynamically:

import de from '@transferwise/components/build/i18n/de.json';

const locale = 'zh-HK';

Or you can load them all at once:

import translations from '@transferwise/components/build/i18n';

To avoid locale code mapping hassle you can use our internal mapping API:

import { mapLocale, LOCALES, DEFAULT_LOCALE } from "@transferwise/components/build/es/polyfill/common/locale";

Note: Provider must be used in repositories which bundle components (i.e. lists @transferwise/components as a dependency). For repositories which don't bundle components (typically those that list it as a peerDependency) it is unnecessary (often it's similar component libraries).

You may need to add it to your development environment (you can do this in Storybook via decorators), demo pages or tests.

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 neptune-core.css, or that and neptune-addons.css. Core includes normalising and base styles such as typography. Addons provide a number of utility classes for display, spacing and more.

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

// Everything
import '@transferwise/neptune-css/dist/css/neptune.css';

// Core
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 + polyfill424.944 Kb (gzip:~128.134 Kb)None.
UMD379.937 Kb (gzip:~110.972 Kb)You must override the default import and include your own polyfill.
ES + polyfill354.388 KbNone.
ES342.68 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