Iris Conversions

Converting legacy widgets 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.

Before continuing, make sure that Iris is included in your page. Please review the "Include Iris" tab for more details.

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.


Since Iris components have all of the styling needed to function, the recommended path to start is to comment out (or delete if you are feeling brave) all of the existing CSS that is widget specific. This will ensure that there are no naming collisions in the existing stylesheet and provide a clean foundation to begin the conversion. 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.
  • 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.
This page is a guide on how to make sure the Iris library is included in your environment.

Building on the Alkami Platform

If you are building an experience that will be deployed on the Alkami platform, there is nothing specific that needs to be done. The Iris library and additional vendor libraries are automatically included and registered in the global scope. Code can be authored with the assumption that Iris will be available and already initialized by the time any other JavaScript is executed.

Building an External Experience

To build an experience using Iris outside of the Alkami platform, there are a handful of files that need to be included. Each time a new version of the Iris library is published, all of these files are pushed to a CDN that can be referenced from any external site.

CSS files

These files should be included in the <head> tag (preferably as the last files).

Iris Library

The main stylesheet for the library. This contains all of the CSS needed for individual components.

Theme file

In order to get proper branding colors, a theme file is needed for the components. Please include the default theme or email the Iris team for an institution specific brand file.


If you would like to leverage the icons in Iris, please also include the base icons file.

Foundation Styles

If you are using the 2.x.x version of Iris and would like the utility classes and grid functionality, please also include the foundation stylesheet.

NOTE: This was included in the main stylesheet in pre 2.x.x versions.


    <link rel="stylesheet" href="">
    <link rel="stylesheet" href="">
    <link rel="stylesheet" href="">
    <link rel="stylesheet" href="">

JS Files

These files should be included just before the close of the <body> tag. On page load (read: DOM ready event) the iris.min.js file will execute, create / bind to any of the components currently on the page, and set up all event listeners as defined in the components.

Iris Library

This is the main JavaScript file for the library. It contains all of the functionality needed for individual components.


If using components that require specific positioning (e.g., tooltips, popovers), popper.min.js is a required peer dependency. Please include this library just before the iris.min.js file.


If you are using the 2.x.x version of Iris and need to support IE11, please also include the polyfills JavaScript version to ensure compatibility.

NOTE: This was included in the main script in pre 2.x.x versions.

Example Includes

    <script src=""></script>
    <script src=""></script>
    <script src=""></script>
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.