Iris Conversions

Converting legacy pages can be challenging. This guide is to provide some helpful tips and direction when starting on that journey.

The conversion begins

If you are reading this guide, that probably means you are starting on an Iris conversion project. While this can be a challenging endeavor, this document is here to give some starting direction and answer a few questions about how to get started.

NOTE: This guide is targeted at developers performing a FULL conversion of an existing interaction. If the task at hand is to convert a subset of page elements to use Iris components (e.g. only converting dropdowns on the page) please refer to the specific component's documentation on how to implement it.

First Steps

With any legacy conversion in the web world, the first thing to do is read through the existing codebase and understand exactly what it is doing. This will be crucial when validating the new code to ensure it has feature parity with the original intent of the existing code. This can take many different forms, but before embarking on the development task, be able to answer these questions.

  • What are the expected user flows (e.g. how do I get from the start to the end of the feature)?
  • What is the user experience currently in this feature (are there modals to prompt for user input, do the sections fade in after page load, etc).
  • Are there any edge cases to pay attention to (error and loading states, server submission errors, network connectivity notifications, etc).

If working on an internal Alkami product answers to the bullet points above should come from UX and / or the Product Owner in the form of documentation, wireframes, InVision Projects or all three. These types of documentation will also be needed to aid the QA effort following the conversion.

Including Iris

If the pages being converted are loaded in an application that includes Iris globally (e.g. building a widget in ORB), please skip this step.

Installing the Iris Package

Iris is currently only available from Alkami's private package repository and CDN.

To get the package you will need to add the package repository as a scope to your project via .npmrc.

# Update the registry for Alkami scoped packages

Once configured You should then be able to install the package like any other using npm when you are on the Alkami network.

npm install @alkami/iris @alkami/iris-theme-overrides

Using Iris From the CDN

The following urls are needed to include Iris:

Reach out to for questions or additional information about the package repository and CDN.

Getting Iris Onto the Page

Including Iris into a page has two file dependencies: the iris.min.css and iris.min.js. Both of these files need to be included on the page for the components to look and act as designed. The CSS file should be loaded in the <head> tag (preferably as the last file), and the JS file should be included just before the close of the <body> tag (again, preferably as the last file). On page load (read: DOM ready event) the iris.min.js file will execute and create / bind to any of the components currently on the page, and set up all event listeners as defined in the components. For more information about a specific component and how it behaves, please see the dedicated documentation page for that specific component.

Additionally, if wanting to use certain components that require specific positioning (tooltips and popovers being great examples of this), popper.min.js is a required peer dependency. It is minified in the package and also provided via the CDN. Please add that library in just BEFORE the iris.min.js file is included.

NOTE: If the page being converted loads dynamically (e.g. utilizes a JavaScript framework), the Iris init function will need to be called manually when the content has finished rendering. In those situations, run this line of code when the page is officially ready.



Since Iris components have all of the styling needed to bring them to life, the recommended path to start is to comment out (or delete if you are feeling brave) all of the existing CSS that is specific to that page. This will ensure that there are no naming collisions in the existing stylesheet and provide a clean foundation to begin the work. Later on during the "Cleanup" section, a review of those styes can be done and whatever needed added back in.

HTML & JavaScript

Since the HTML and JS files will have the majority of the changes, it is recommended to duplicate those files and maintain reference-able backups of what currently exists. Once those backups have been made, feel free to delete the markup of current elements and the various bindings directly tied to that markup. Helper methods, page structure elements and view models, can remain, but anything that Iris will replace should be deleted before beginning.

<!-- There is no need to remove structural page elements -->
<div class="page-wrapper">

<!-- But delete markup that will be replaced -->
<select id="account">
// This is fine to leave around
const formatCurrency = (amount) => {
    // Currency format logic

// But delete a section like this
const accountSelectionElement = document.getElementById('account');
accountSelectionElement.addEventListener('click', (event) => {
    // Event handler logic

The reason to delete anything that is element specific is to limit the amount of legacy code that could adversely affect Iris components and the bindings they set up. This will make the process much easier by removing anything that could conflict with the new conversion code.

Starting to add in Iris components

Once the foundational work is taken care of, it's time to start adding components. If working with our internal UX team, take a few minutes to review the conversion designs which reference the components to be used and start the process of adding them in one by one. If performing the conversion without a conversion design, instead try to familiarize yourself with the appropriate Iris component replacements that will be needed for the current design iteration.

Adding each component is a fairly painless process. The recommended method is to navigate to the component's documentation page's code tab, find the closest example to what is needed, click the "Copy" button over the example section, and paste it into the HTML file. From here, you can make changes to duplicate and modify the component to fit your needs.

Final Cleanup

Once the conversion is complete, go back and delete any commented out CSS, remove the backup files created earlier, send it off for QA validation, and go grab a beer.

Congratulations! Your Iris conversion is complete.

Let's Recap

When performing an Iris conversion, here are the main steps to take:

  • Understand what the current code is doing and the expected functionality.
  • Review any designs, workflows, wireframes, documentation, configuration, etc. surrounding the feature.
  • Include iris.min.js and iris.min.css (and popper.min.js if needed) into the page being converted.
  • Comment out or remove any CSS, HTML, or JS that will be replaced by Iris components.
  • Add in the Iris components one by one, ensuring expected functionality along the way.
  • Delete all leftover / still commented out CSS, JS, HTML from the previous files.
These are a collection of common issues that might come up during an Iris conversion. If you are running into problems, read through these to give some direction on where to go.

My component doesn't look right

Interesting! The challenge when implementing a new library into any legacy system is the possible collisions that happen, particularly with stylesheets. The "C" in CSS stands for "Cascading" and most likely the component that is not appearing like the examples is being affected by that cascading nature. The best way to trace this down is to inspect the component in the browser's devtools and look for any CSS rules that are causing the appearance to change. Once you have that chased down, there are two options to solve for this case:

Remove or refactor the rule in question (recommended method):

// An overly specific or !important rule
.offending-css-rule * {
    color: brightred !important;

// Can be refactored to be less pervasive
.less-offending-css-rule {
    color: brightred;

If that's not possible, create a specific override to that rule that is localized to the Iris component (most likely using an !important modifier):

// Add an !important modifier for the property being overridden
.iris-[component_name] {
    color: #333333 !important;

// Or localize to the specific markup of the page
.page-wrapper .iris-[component_name] {
    color: #333333;

The least brittle method is always to refactor the current code and let Iris control all of its own styling.

If circumstances force an override to be written at a page level (the second option), keep in mind that as the Iris library changes, the overrides will also need to be updated to maintain the proper styling.

My component doesn't work!

If a component doesn't seem like it is functioning properly, there are a few methods of troubleshooting depending on the component in question. The best piece of advice to follow in a situation like this is to go back and re-read the documentation. Many times there is a minor nuance referenced in the docs that will help solve the issue. If there are still problems, it is most likely one of two categories of issues:

CSS only components

A CSS only component is one that functions entirely without JavaScript. Some good examples of these are checkboxes, radio buttons, and toggles. Since no JavaScript is applied for the functionality, the issue is almost exclusively within the markup itself, since the selectors rely heavily on an expected layout of the HTML. In cases like this, check these items before diving any deeper:

  • Ensure all input elements have a unique id attribute.
  • Ensure all label elements have a for attribute corresponding to the associated input element.
  • Confirm that no other elements are being inserted into the DOM at that location (a hidden input field for example).
  • Inspect the markup in devtools and confirm that the CSS rules are not being overridden by another rule (see issue #1 on this page for more details).

JS components

A JS component is one that requires JavaScript for it to function appropriately. To tell if a component has JavaScript involved, check the respective "code" tab on the documentation page and look for an "API" section. If one exists, the component has JavaScript involved behind the scenes. In cases like this, the issue most likely stems from the Iris library initiating before the markup on the page has rendered. Since Iris attempts to start up on the DOMReady event, if any markup is not available on the page (for instance when using a JS framework), the element will not be available to attach to.

If using a JS framework (or doing heavy DOM manipulation), call the main Iris init method once the rendering has completed.

const createPageMarkupAndBindJsFramework = () => {
    // Your specific page creation logic


// Now that the page is built, call the main iris init function

If only changing a few components, call the specific component's init method instead.

const newIrisElement = document.createElement('<div>');

const pageElement = document.getElementById('page_wrapper');

// Now that the element has been appended to the DOM, call the specific init method

NOTE: This method can also be used for instances when a component is added to the page after the initial rendering has occurred.