How to theme FusionAuth’s advanced registration forms

When a user is registering, the last thing you want to do is get in their way or confuse them. In this tutorial, you’ll improve an advanced registration form’s display by modifying a theme.

Previously, we built a self service registration form for a real estate webapp and used FusionAuth as the auth server. It was a two step form which captured information about their home buying needs. However, the form had a few rough elements. In particular, it wasn’t clear which data someone was supposed to enter into which form field.

This tutorial builds on the previous one and walks through changing the theme. While this tutorial will reference the previous form, feel free to apply it to any form you’ve created as well.

This is part of a three part series. Here are all the posts:

  1. How to use FusionAuth’s advanced registration forms
  2. How to theme FusionAuth’s advanced registration forms (this one)
  3. Building a user profile portal with Flask, OAuth, and APIs

FusionAuth setup

You may also check no endpoints or methods. This creates a super-user key, able to do anything. Well, at least able to access all of the FusionAuth API. This is fine for a tutorial, but for production, please limit access.

Creating a custom theme for a single or multi-tenant configuration

This is the theme you’ll modify throughout the rest of this blog post.

Navigate to “Customizations” and then “Themes”. Duplicate the existing “FusionAuth” theme. Rename your theme to something meaningful, such as “Real Estate Application”. Before you save it by clicking the blue icon, it should look like this:

Image for post
Image for post

Navigate to “Tenants” and then edit the “Default” tenant. Go to the “General” tab and update the “Login theme” setting to the new theme. Save the configuration when the screen looks like:

Image for post
Image for post

Customizing our theme

Image for post
Image for post

We’re going to add in understandable placeholders and labels, but there’s a lot more you can do; check out the theming documentation for more.

To begin, in the administrative user interface, navigate to “Customizations” and then “Themes”. Find the theme you created above and copy its id; mine is de03191a-9369-4732-a9c4-0467d1f26482.

Modifying a theme via API

These scripts assume you are running FusionAuth at http://localhost:9011; if not, adjust accordingly. These scripts are also available on GitHub. They also require you to have jq and python3 installed locally.

Retrieving a theme file for local editing

The script turns embedded newlines into real ones:

While this script only works for the messages file, it can be tweaked to handle other parts of a theme, such as the HTML template files. This is left as an exercise for the reader; pull requests are welcome.

Modifying the messages file

It’s about 200 lines; the above is an excerpt. Open it in your favorite text editor.

If you are interested in localized messages, check out the fusionauth-localization project.

To improve the registration form, add values to the “Custom Registration” section. Maintaining sections in this property file isn’t enforced (it’s not a .ini file) but it's a good idea to change only what is needed. Upgrades to FusionAuth may change the properties file and you will have to merge the changes, so simpler is better. Here is the section to which you're going to add lines:

The keys of the messages file match the field keys for the registration form. Here’s what you’d add to set up placeholders for the real estate application registration form:

You aren’t limited to placeholders, either. You can add validation messages to the section starting with: # Custom Registration form validation errors. You can examine the Default validation errors section for examples of all the errors available.

Append the key to provide specific errors for a given form field. For example, to display a user friendly error message when price range information is omitted, add these properties:

If any of the values you add to defaultmessages.txt have a double quote in them, escape it: \". This prevents issues when this file is converted back into JSON, which must happen before the changes are reflected in FusionAuth.

Updating the theme in FusionAuth

This script performs all the above actions on the defaultmessages.txt file:

Run this script with the modified defaultMessages.txt file. This will apply the changes to your theme.

To view the changes, find the registration URL by going to the “Application” tab in the FusionAuth administrative user interface. View your application and copy the registration URL:

Image for post
Image for post

Open an incognito window and visit this URL. You should see your shiny new placeholders on the first page:

Image for post
Image for post

If you fill out the first step, you’ll see the second page with the correct hints as well:

Image for post
Image for post

Validation and theming

Image for post
Image for post

Adding form labels

Navigate to “Themes” and edit your theme. Click on “Helpers” and scroll to the bottom. You’ll be modifying the customField macro. Here's the default implementation for this FreeMarker macro:

It looks a little wonky if you aren’t used to it, but this is a series of if/then statements which get executed against every custom field as the user interface is being generated. The macro looks at each field definition and creates the correct HTML element. Well, technically, it calls another macro such as input or select, but you get what I mean. For instance, a password field will be rendered as an HTML input field with the type password.

Let’s add a label to each field. Right after [#assign fieldId = field.key?replace(".", "_") /], add this:

Open an incognito window and go through the registration flow again. You should see labels for both steps. These label values will be pulled from your message bundles, so can be localized in the same way as any of the other messages. As a bonus, because you used the label HTML element, you can now click on the text label and the browser will put the cursor into the text input field. User experience win!

Image for post
Image for post

If you complete the first step, you can see labels are present on the second step as well:

Image for post
Image for post

Previewing a theme

Navigate to “Customizations” then to “Themes”. Choose your theme, then click the preview link (the green magnifying glass):

Image for post
Image for post

Doing this will open a new tab. Click “OAuth register” in the left hand navigation and you’ll see the theme as it would be rendered. You can even switch between steps. Below is the preview for the second step:

Image for post
Image for post


If you are using FusionAuth registration forms, be sure to customize the default templates to improve users’ experience. FusionAuth’s themes can be manipulated both in the administrative user interface and by API calls.

But what about after the registration? This information is available via the FusionAuth APIs, in the and fields. It is also available for viewing, but not editing, in the administrative user interface.

Let’s build a small portal page for the user to see their data. You can retrieve and modify user data using the APIs and in a future blog post we’ll see exactly how to do that.

Originally published at

Auth for built for devs. Installs on any server, anywhere in the world. Integrates with any codebase.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store