Configuring branding

Implementers can configure various aspects of the user interface to match their branding. This includes:

Changing the logo on the login screen
Changing the logo on the navbar
Changing brand colors
Changing the favicon

Changing logos

Logos are used in several places in O3:

The login page
The navbar
Optionally in printouts when configured

The default logo used in the O3 login page is the OpenMRS SVG sprite defined here (opens in a new tab). You can override it by providing a valid image src URL as the value of src property in the login frontend module's configuration schema. Below is a snippet of how this could look like:

{
  "@openmrs/esm-login-app": {
    "logo": {
      "src": "https://data.kenyahmis.org/openmrs/images/logos/kenyaemr-logo.svg",
      "alt": "KenyaEMR logo"
    }
  }
}

In this example, the logo SVG specified at that URL will be applied as the default login page logo. To persist this change, you will need to commit this configuration to your instance's frontend configuration. To do this in the distro reference application, you'll need to:

Step 1

Add your resource to a directory in the distro. For example, a logo.png file can be added to the frontend/resources directory.

Step 2

Add this line to the Dockerfile in the frontend directory:

COPY ./resources/logo.png /usr/share/nginx/html

This will copy the logo to the root of the application.

Step 3

Add the following snippet to the config-core_demo.json file in the frontend directory:

ℹ️

Note that the paths to your configuration files might be different. Adjust the paths to match your application's structure.

{
  "@openmrs/esm-login-app": {
    "logo": {
      "src": "${openmrsSpaBase}/logo.png",
      "alt": "Logo"
    }
  }
}

This scopes the logo to the login app only.

Changing the logo used in the navbar

The default logo used on the navbar is configured here (opens in a new tab). You can optionally use a string or an SVG image as the navbar logo. To override the navbar logo, use a configuration similar to the snippet below:

{
  "@openmrs/esm-primary-navigation-app": {
    "logo": {
      // Using an SVG image URL
      "src": "https://data.kenyahmis.org/openmrs/images/logos/kenyaemr-logo-nav.svg"
      // Or, using a string
      "name": "KenyaEMR",
    }
  }
}

To persist your changes to your distro, follow the same steps in the section above with the following config file snippet in the config-core_demo.json file:

{
  "@openmrs/esm-primary-navigation-app": {
    "src": "${openmrsSpaBase}/logo.png",
    "alt": "Logo"
  }
}

This scopes the logo to the primary navigation app only.

ℹ️

If the image you're using for the logo is hosted outside the OpenMRS distribution, you might need to modify the Content Security Policy to allow the image to be loaded. To do so, you would need to tweak the map block that defines CSP headers in the nginx configuration file (opens in a new tab) in the gateway directory. You might want to add a img-src * directive that allows all images to be loaded. img-src * allows loading images from any origin, including your domain, any external domains and data URIs.

Changing the favicon

To change the favicon, you'd need to add the favicon file to your distro. You'd then add the following line to the frontend Dockerfile (opens in a new tab):

COPY ./path-to-the-favicon /usr/share/nginx/html

This will copy the favicon to the root of the application.

ℹ️

Note: You would need to rebuild the application for this change to come into effect.

Changing brand colors

Implementers can change the default brand colors specified in the styleguide, overriding them with hex values that conform to their own brand colors. The default brand colors that determine how the UI looks like are defined in the styleguide configuration schema. To override them, use a configuration similar to the snippet below:

{
  "@openmrs/esm-styleguide": {
    "Brand color #1": "#00473F", // The 'primary' color
    "Brand color #2": "#363463", // The 'secondary' color
    "Brand color #3": "#51A351" // The 'tertiary' color
  }
}