Skip to main content
Last modified: September 26, 2025
Alias mapping enables you to create field mappings in a module so that you can move, rename, or replace its fields without impacting pages that are using the module. For example, a module is being used on a live page. You want to move some fields into the Styles tab, such as color or font, but a content creator has already selected values for those fields in the editor. If you were to move those fields without setting up alias mapping, HubSpot would not be able to relocate those fields and they would revert to their default values, which would undo the styling on the live page. Instead, you can include an aliases_mapping property to map the field to another one in fields.json. Then, when a value has not been set for the original field, HubSpot will check if a value exists in the mapped field. If no value exists in the mapped field either, it will use the default value instead. This property can be used to map field values between different versions of a module only when the stored data type of the old field is the same as the new field’s stored data type. For a visual walkthrough of this feature, check out the video below.
To migrate existing fields to aliases:
  1. Create new fields and map them to old fields using the aliases_mapping property in the fields.json file.
  2. Remove the old field definition.
  3. Update the module.html file to use the new fields definition.
Please note:
  • You cannot map fields that are of a different data type to each other. For example, you can’t map a background gradient field to an image field. The stored value has to be a valid value for the new field’s type.
  • When creating a new field with an alias mapping to an old field, the default values and required properties of both fields should be the same.
Below are examples of implementing this for both simple and complex changes:

​
Simple implementation

In simple situations, the field type of the old field and the field type of the new field should be the same. For example:
  • Old color field to new color field.
  • Old text field to new text field.
  • Old spacing field to new spacing field.
Below is an example of using aliases_mapping when moving a color field from the module’s Content tab to the Styles tab. Original module code:
  • JSON
[
  {
    "label": "Button Color",
    "name": "old_button_color_field",
    "type": "color",
    "required": true,
    "default": {
      "color": "#FFFFFF",
      "opacity": 100
    }
  }
]
Updated module code:
  • JSON
[
  {
    "label": "Styles",
    "name": "styles",
    "type": "group",
    "tab": "STYLE",
    "children": [
      {
        "label": "Button Color",
        "name": "new_button_color_field",
        "type": "color",
        "required": true,
        "aliases_mapping": {
          "property_aliases_paths": {
            "new_button_color_field": [
              "old_button_color_field"
            ]
          }
        },
        "default": {
          "color": "#FFFFFF",
          "opacity": 100
        }
      }
    ]
  }
]

​
Complex implementation

In more complex situations, you can also map fields to subfields or other module field types as long as the data type is the same, and the new field’s subfield type matches. Subfields are the properties within the field’s stored value object. For example:
  • Mapping a Rich text field to a Text field, as the values in both fields are stored as strings.
  • Consolidating typography fields, such as changing from a number field for font size, to use a font field (which has a font size sub field). You can add an alias for the size subfield to map it to the old number field by using dot notation.
Below is an example of changing the font sizing option from a number field to a font field which has a font size sub field. Original module code:
  • JSON
[
  {
    "name": "my_number_field",
    "label": "Number field",
    "required": false,
    "locked": false,
    "display": "text",
    "step": 1,
    "type": "number",
    "min": null,
    "max": null,
    "inline_help_text": "",
    "help_text": "",
    "default": null
  }
]
Updated module code:
  • JSON
[
  {
    "name": "my_font_field",
    "label": "font_field",
    "required": false,
    "locked": false,
    "inline_help_text": "",
    "help_text": "",
    "load_external_fonts": true,
    "type": "font",
    "aliases_mapping": {
      "property_aliases_paths": {
        "my_font_field.size": [
          "my_number_field"
        ]
      }
    },
    "default": {
      "size": 12,
      "font": "Merriweather",
      "font_set": "GOOGLE",
      "size_unit": "px",
      "color": "#000",
      "styles": {}
    }
  }
]