Installation

We recommend that you install Modes UI locally. Another option for testing is fetching the library package from the documentation site. You can also cherry pick individual components for faster load times.

If you’re using React, make sure to check out the page for React.

Local installation

The ideal way of installing Modes UI is locally installing it from our private npm registry. Currently the package is available through both GitHub and Azure, but we strongly recommend using GitHub Packages for installation. The Azure package will be deprecated at a later date.

Authentication

To authenticate to GitHub Packages, and install the library package:

• you must add @metsooutotec:registry=https://npm.pkg.github.com to your project’s .npmrc configuration file, located in your projects root. This guides the npm installation to look for the package in this private GitHub packages registry.
• you must create a classic personal access token for your enterprise GitHub account, and add the token to your personal, local, .npmrc folder, as described in GitHub’s documentation here. The PAT must be a classic token in GitHub with at least read:packages scope, and you must click ‘Configure SSO’ and then authorize the Metso organization for your newly created PAT.

Then, simply install the package with the following command:

npm install @metsooutotec/modes-web-components

To fetch the package from Azure DevOps (legacy, will be deprecated):

If you have issues with access rights, try adding @mogroup:registry=https://pkgs.dev.azure.com/outotec/_packaging/Outotec.React/npm/registry/ to your project’s .npmrc file. For authentication, you will need to create a personal access token in Azure. See DSUI’s getting started page for more information, as the authentication is the same for both libraries since they are hosted in the same place in Azure.

For Azure, use the following command:

npm install @mogroup/modes-ui

It’s up to you to make the source files available to your app. One way to do this is to create a route in your app called /modes-ui that serves static files from node_modules/@metsooutotec/modes-web-components.

Once you’ve done that, add the following tags to your page. Make sure to update href and src so they point to the route you created.

<link rel="stylesheet" href="/modes-web-components/dist/themes/light.css" />
<script type="module" src="/modes-web-components/dist/modes-ui.js"></script>

Using the experimental autoloader

You can also opt-in to the experimental autoloader instead. This will dynamically lazy load the relevant components instead of incurring the size of the entire library on initial load (which importing modes-ui.js will do).

<script type="module" src="/modes-web-components/dist/modes-ui-autoloader.js"></script>

Although for most projects, you should use a bundler.

Setting the base path

Some components rely on assets (icons, images, etc.) and Modes UI needs to know where they’re located. For convenience, Modes UI will try to auto-detect the correct location based on the script you’ve loaded it from. This assumes assets are colocated with modes-ui.js and will “just work” for most users.

However, if you’re cherry picking or bundling Modes UI, you’ll need to set the base path. You can do this one of two ways.

<!-- Option 1: the data-modesui attribute -->
<script src="bundle.js" data-modesui="/path/to/modes-web-components/dist"></script>

<!-- Option 2: the setBasePath() method -->
<script src="bundle.js"></script>
<script type="module">
  import { setBasePath } from 'modes-web-components/dist/utilities/base-path.js';
  setBasePath('/path/to/modes-web-components/dist');
</script>

Theming

You will need to import Modes UI’s theme .css files to ensure components are rendered in proper styles. These theme files can be imported through module imports, or inside another .css/.scss file.

Modules (.jsx/.tsx files):

import '@metsooutotec/modes-web-components/dist/themes/light.css';
/* Import dark.css if you want to have dark mode support **/
import '@metsooutotec/modes-web-components/dist/themes/dark.css';

CSS (.css/.scss files):

@import '~@metsooutotec/modes-web-components/dist/themes/light.css';
/* Import dark.css if you want to have dark mode support **/
@import '~@metsooutotec/modes-web-components/dist/themes/dark.css';

Light & dark theme

If you want to load the light or dark theme based on the user’s prefers-color-scheme setting, use this. The media attributes ensure that only the user’s preferred theme stylesheet loads and the onload attribute sets the appropriate theme class on the <html> element.

<link
  rel="stylesheet"
  media="(prefers-color-scheme:light)"
  href="@metsooutotec/modes-web-components/dist/themes/light.css"
/>
<link
  rel="stylesheet"
  media="(prefers-color-scheme:dark)"
  href="@metsooutotec/modes-web-components/dist/themes/dark.css"
  onload="document.documentElement.classList.add('mo-theme-dark');"
/>

Now you can start using Modes UI!

Cherry picking

The previous approach is the easiest way to load Modes UI, but easy isn’t always efficient. You’ll incur the full size of the library even if you only use a handful of components. This is convenient for prototyping or if you’re using most of the components, but it may result in longer load times in production. To improve this, you can cherry pick the components you need.

Cherry picking can be done from your local installation. This will limit the number of files the browser has to download and reduce the amount of bytes being transferred. The disadvantage is that you need to load component manually.

Here’s an example that loads only the button component. Again, if you’re not using a module resolver, you’ll need to adjust the path to point to the folder Modes UI is in.

<link rel="stylesheet" href="/path/to/modes-web-components/dist/themes/light.css" />

<script type="module" data-modesui="/path/to/modes-web-components/dist">
  import '@metsooutotec/modes-web-components/dist/components/button/button.js';

  // <mo-button> is ready to use!
</script>

You can copy and paste the code to import a component from the “Importing” section of the component’s documentation.

<script type="module" src="https://modes-web.metso.com/dist/components/button/button.js"></script>
<!-- <mo-button> is ready to use! -->

Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the “Dependencies” section of its docs.

Bundling

Modes UI is distributed as a collection of standard ES modules that all modern browsers can understand. However, importing a lot of modules can result in a lot of HTTP requests and potentially longer load times. Using a CDN can alleviate this, but some users may wish to further optimize their imports with a bundler.

To use Modes UI with a bundler, first install Modes UI along with your bundler of choice.

npm install @metsooutotec/modes-web-components

Now it’s time to configure your bundler. Configurations vary for each tool, but here are some examples to help you get started.

Example webpack config

const path = require('path');
const CopyPlugin = require('copy-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  module: {
    // Bundle styles into main.css
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader']
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin(),
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, 'node_modules/@metsooutotec/modes-web-components/dist/assets'),
          to: path.resolve(__dirname, 'dist/modes-ui/assets')
        }
      ]
    })
  ]
};

Once your bundler is configured, you’ll be able to import Modes UI components and utilities.

import '@metsooutotec/modes-web-components/dist/themes/light.css';
import '@metsooutotec/modes-web-components/dist/components/button/button.js';
import '@metsooutotec/modes-web-components/dist/components/icon/icon.js';
import '@metsooutotec/modes-web-components/dist/components/input/input.js';
import '@metsooutotec/modes-web-components/dist/components/rating/rating.js';
import { setBasePath } from 'modes-web-components/dist/utilities/base-path.js';

// Set the base path to the folder you copied Modes UI's assets to
setBasePath('/path/to/modes-web-components/dist');

// <mo-button>, <mo-icon>, <mo-input>, and <mo-rating> are ready to use!