Customizations using JavaScript in the Loginapp Design Kit

The Loginapp Design Kit provides more powerful and advanced types of customizations using JavaScript.

JavaScript customizations

To enable customizations in JavaScript, the Loginapp Design Kit provides a file to contain all JavaScript code located at:

Programmatically, the following classes are intended as an API to extend from. API classes are characterized by having api in their namespace.

Every custom class must be registered before it can be used.


Registers with



Customizing the layout of an existing page.

  • In particular:
  • Header
  • Footer
  • Content Frame

Customization of the Loginapp UI layout using default HTML files


Modify or extend an existing page of the Loginapp UI.

  • Examples:
  • Adding new UI elements to a page, e.g. a subtitle.
  • Changing the order UI elements.
  • Adding dynamic behavior, e.g. a password meter.

Customizing an existing product page using the Loginapp Design Kit


Provide an entirely new page written in JavaScript.

The difference between changing an existing page and adding a new page is all about the control of the flow in the Loginapp UI.

  • Existing Page:
  • Flow control remains under the control of the product. The Loginapp UI will call all registered and applicable methods during all lifecycle events that require them.
  • NewPage:
  • Flow control is handed to the JavaScript Code of the new Page. The page must provide the content and potential function after the rendering of the page. The page must also deal with both successful and unsuccessful flow responses.

Adding new pages using the Loginapp Design Kit

These are classes using JavaScripts ES6 class declarations. In custom code, they are meant to be extended. To implement custom behavior, methods can be overwritten.

In the remainder of this documentation, the available methods and the semantics of those methods are described in detail. Note that methods not explicitly described in this documentation are considered internal and may change without further notice.

Using JavaScript modules

For larger projects or more advanced customizations, writing all JavaScript in just one large file can become confusing. The Loginapp Design Kit, therefore, supports the usage of JavaScript modules and allows to modularize code into separate JavaScript files containing functions or classes. Using JavaScript modules is also advantageous to include 3rd party JavaScript libraries.

With JavaScript modules, you may, e.g., keep a separate JavaScript file per CustomJavaScriptPage, CustomProductPage, or CustomLayout.

Instead of having the code of a page directly in iam-custom.js, it can be extracted to a separate file like my-custom-password-page.js where the class MyCustomPasswordPage is made accessible to other JavaScript modules using the export keyword.

export class MyCustomPasswordPage extends iam.api.types.CustomProductPage { 
    isApplicable({pageId, flowId, stepId}) { 
        return pageId === 'iamAuthPassword'; // Only apply to the password page 
    onPageEnter() { 
        console.log('This is just an example'); 

In iam-custom.js , the file can be referenced and the exported class MyCustomPasswordPage can be imported using the import keyword:

import {MyCustomPasswordPage} from './my-custom-password-page.js'; 
iam.api.customizing.initialize = function () { 
    iam.api.customizing.registerPage(new MyCustomPasswordPage()); 

Note that in this example, my-custom-password-page.js is located in the same folder as iam-custom.js. However, you may choose any folder or folder structure for your additional JavaScript files as long as they reside within the assets folder.

More specifically, it is recommended to choose $CUSTOM_DIRECTORY/src/assets/custom/js as the parent folder for all your JavaScript files or nested folders containing JavaScript.

Note that API methods like iam.api.customizing.registerPage or iam.api.customizing.registerLayout can only be invoked when called within iam.api.customizing.initialize.

Applying customization

To make the JavaScript customization of the Loginapp UI flexible (i.e. specific to only a certain page or flow), every customization must provide a method isApplicable . This method is called with the current values of flowId, stepId and pageId and returns either true or false. With this method, the Loginapp UI is able to determine if a registered customization is to be applied to the page that is to be rendered at this point. If none of the customizations return true, the default customization from the product is used.

Avoid constructors

Like most programming languages, ES6 classes provide constructors that are invoked when instantiating an object. When extending from classes provided by IAM as an API, it is highly recommended to avoid using the constructor for HTML rendering and application logic. At the moment the constructor is invoked, the rest of the Loginapp UI usually is not yet ready. Also, the constructor is only invoked once whereas custom implementations are expected to work on multiple pages, e.g. for a layout.

Instead of using the constructor, stick to the methods provided as API.

Browser caching

IAM by default sets caching headers for static assets like images, fonts, etc. For assets used through SASS, the caching is automatically handled correctly. During the compilation from SASS to CSS, every asset name is extended with a hash value. Changes in assets will change the hash value and therefore change file names. This forces all browsers to download the new asset.

Care should be taken when using static files in HTML that are injected through JavaScript (e.g. using custom blocks or in render methods). If such an approach is taken, these files must be versioned manually to deal with browser caching correctly.

To avoid problems with caching, it is recommended to use SASS whenever possible.