Web SDK Theme Customization

Alloy SDK supports customizing the UI so that you can match the look and feel of your application. Customizations apply to the following plugins

Alloy Document Verification
Prove Identity
Vouched (only the Theme object applies)

While you are not able to change the layout or entirely replace components for another, you are able to change things like background color, text color, border, border radius, and more. These customized visuals are available in the default, focus, and hover states of the components.

To customize the SDK,

Start by using theme. Themes have variables like backgroundColor and textColor that let you control the overall style of the UI.
If you need more granular control than theme provides, you can reach for component override, which allows you to override specific visual properties of specific components like PrimaryButton and Header for specific states (default, hover, and focus states).
Construct the customStyle object and add to the initParam that you use to initialize Alloy SDK via alloy.init(initParam).

📘
You can think of every field in the customization API as a more tightly-scoped inline style css. For example, whether it's for a theme or a componentOverride, the backgroundColor behaves exactly the same way you would expect an inline style backgroundColor to work in html/css.

Theme

Theme styles the overall UI. Theme relies on our internal logic to distribute the visual properties you pass in through the theme object in the InitParam. Because Theme relies on our internal logic, you won't have granular control over how the styles are applied but it will help you get going faster.

Here is a sample of initParam with a customStyle object that has a theme.

const initParam = {
    ...
    customStyle: {
        theme: {
            primaryColor: '#F46A35',
            backgroundColor: '#ffffff',
            textColor: '#121212',
            borderRadius: '10px',
         },
         componentOverride: {
          ...
          }
    }
    ...
}

See all Theme fields

type CustomTheme = {
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  borderRadius?: string;
  iconColor?: string;
  successColor?: string;
  errorColor?: string;
}

Field	description
`primaryColor`	The accent color of the SDK. Components like the Primary Button and Help Banner in our SDK UI will be styled by the primaryColor. Theme API has built-in logic that computes the optimal text color as well as the hover color for these components and assigns them for you automatically.
`backgroundColor`	The background color of the SDK. Indirectly, it will also style our transparent components like entity selector and exit buttons.
`textColor`	The default text color of the SDK. Make sure the contrast between backgroundColor and textColor are great enough for the text to be accessible.
`borderRadius`	The border radius of all elements with borders in the SDK.
`iconColor`	The color of the Icons that are in the SDK.
`successColor`	The color of any components or elements that are related to success status like the success checkmark.

If you want to eject out of the built-in logic of the Theme API or feel that the level of control the Theme API provides isn't enough, that is when you move on to Component Override API.

Component Override

Component Override gives you the ability to granularly control components in the SDK UI. This helps with ejecting from the default behavior of the Theme or replicating the look and feel of your application down to the last pixel.

Here is a sample customStyle object with component override.

const customStyle = {
    theme: {
    ...
    },
    componentOverride: {
      PrimaryButton: {
        default: {
          backgroundColor: '#F46A35',
          textColor: '#121212',
        },
        hover: {
          backgroundColor: '#f27f54'
        },
        focus: {
          border: '1px solid blue'
        }
      },
      HelpBanner: {
        default: {
          backgroundColor: '#f9f9f9',
          textColor: '#212121',
          border: '0.5px solid rgba(0, 0, 0, 0.1)',
        }
      },
      Header: {
        default: {
          border: '0.5px solid rgba(0, 0, 0, 0.1)',
        },
      },
      PhoneInput: {
        default: {
          backgroundColor: '#f9f9f9',
          border: '0.5px solid rgba(0, 0, 0, 0.1)',
        }
      },
    },
  }

This sample will do the following:

Override the PrimaryButton everywhere in the UI with the supplied textColor for all states, backgroundColor for both default and hover states, and border style for focus state.
Override the HelpBanner everywhere in the UI with a specific backgroundColor, textColor and border styles.
Override the Header with the supplied border style.
Override the PhoneInput's default state with a specific backgroundColor and border style.

You might've noticed from the sample code that the API allows you to pass in specific styles for default, hover and focus states. Interactive components can take in customizations for default, hover and focus states while non-interactive components can only take in default state customization. The only exception is the Phone Input where we currently only allow default state customization despite it being an interactive element.

See all customizable components and fields

Component Name	Image
PrimaryButton
ExitButton
PhoneButton
HelpBanner
PhoneInput
Header

type componentOverride = {
  PrimaryButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
  };
  ExitButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
  };
  PictureButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
  };
  SelectorButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
      iconColor?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
      iconColor?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
      iconColor?: string;
    };
  };
  Header?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      border?: string;
      boxShadow?: string;
      borderRadius?: string;
    };
  };
  HelpBanner?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      border?: string;
      boxShadow?: string;
      borderRadius?: string;
      iconColor?: string;
    };
  };
  PhoneInput?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      border?: string;
      boxShadow?: string;
      borderRadius?: string;
    };
  };
};

See all customization object types

type CustomStyle = {
  theme: CustomTheme;
  componentOverride: ComponentOverride;
}

type CustomTheme = {
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  borderRadius?: string;
  iconColor?: string;
  successColor?: string;
  errorColor?: string;
}

type ComponentOverride = {
  PrimaryButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
  };
  ExitButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
  };
  PictureButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
    };
  };
  SelectorButton?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
      iconColor?: string;
    };
    hover?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
      iconColor?: string;
    };
    focus?: {
      backgroundColor?: string;
      textColor?: string;
      borderRadius?: string;
      border?: string;
      boxShadow?: string;
      iconColor?: string;
    };
  };
  Header?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      border?: string;
      boxShadow?: string;
      borderRadius?: string;
    };
  };
  HelpBanner?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      border?: string;
      boxShadow?: string;
      borderRadius?: string;
      iconColor?: string;
    };
  };
  PhoneInput?: {
    default?: {
      backgroundColor?: string;
      textColor?: string;
      border?: string;
      boxShadow?: string;
      borderRadius?: string;
    };
  };
};