Upgrade an Advanced Theme

FusionAuth version updates sometimes require updates to custom themes. This page explains how to make those updates.

CSS#

If your custom theme includes CSS changes upgrading involves the following steps:

Templates#

When FusionAuth adds functionality to the hosted login pages, we sometimes add or modify theme templates. FusionAuth automatically updates the default theme to include these templates when upgrading versions. If you use a custom advanced theme, you must manually add the new templates and modify your existing templates.

To update your custom theme to use the new templates, follow these steps:

When a version of FusionAuth changes existing templates, you must compare the new theme to your existing version's base theme, then port over the changes to your custom theme.

Messages#

When the hosted login pages gain new functionality, FusionAuth sometimes adds new theme message keys. FusionAuth automatically updates the default theme messages file to include these new keys when upgrading versions. If you use a custom advanced theme, you must manually add the new keys to your theme.

To add the new messages to your theme:

FusionAuth warns you about missing required keys in order to avoid an inadvertent bad user experience. The default display for keys with no valid values in theme Messages is the key text, such as [ExternalAuthenticationException]LinkedInToken, which can be confusing for end users.

You can find these keys by testing the version upgrade on a development instance or comparing releases in the fusionauth-localization repository. Add the new key values to your theme before upgrading to prevent any users from seeing broken key text on your login pages.

Find Differences Between Themes#

To find the difference between the default theme of any two versions of FusionAuth, use the Theme History repository.

FusionAuth tracks the history of changes to the default hosted page themes using Theme History. Use the GitHub diffing interface to see the difference between any two versions. For instance, the following URL shows the difference between versions 1.65.0 and 1.69.0:

https://github.com/FusionAuth/fusionauth-theme-history/compare/1.65.0...1.69.0

Replace the version strings 1.65.0 and 1.69.0 in the example URL above to visualize the difference between any two versions.

Alternatively, you can download the repository and visualize the difference between any two version tags or commits using a diffing tool of your choice.