Module & theme fields best practices

Last updated:

The ability to create fields and group fields poses a User Experience (UX) issue. Especially in the case of style fields, where modules will often have similar styling options.

To understand the issue you'll need to put yourself in the content creator’s shoes. Imagine purchasing a theme, or getting a theme built for you. The theme has 20 modules in it. You go to set the background of a component in one module, the fields are organized one way. You then need to update the background of a different module's component. The fields are organized and labeled differently. Now imagine every single module in that theme has the fields organized differently.

This introduces a few problems:

  • There's no consistent logic to how fields are organized, which makes it difficult to establish muscle memory, and can be a frustrating experience overall.
  • There's no consistent logic to how the fields are named. This can result in having to resort to trial and error - setting the field to see what it controls.

Both issues result in less efficiency and a less than delightful experience for the content creator.

This isn't a rulebook but we do encourage you to use this page as a guide to providing an intuitive experience for content creators.

Before you get started

Below, review the following terms that are used throughout this guide:

  • Component: a smaller piece of a module. For example, an image in an image and text module would be a component. The text in that same module would be a separate component. The term component is referred to in terms of design, and is not a technical HubSpot-specific concept. Components can be content or stylistic.
  • Stylistic or presentational component: a piece of a module that conveys no actual meaning to the site visitor. For example, a drop shadow on cards for a pricing table; If removed the meaning of the content is still the same.
  • Toggle: the boolean field's ability to be displayed as a toggle switch.
  • Text and image module: a common design where an image will be placed next to each other horizontally.

Style fields vs. content fields

You can add style fields to both modules and themes. When added to a module, the style options will appear in the Styles tab of the page editor. Style fields added to a theme will appear in the left sidebar of the theme editor. These fields are separate from the module's content fields, which are used to populate the module with actual content. 


You should use a content field to provide the module's meaningful content, while style fields should be used to control the module's appearance. For example, If you have a text and image module and the image is required to understand the text content, the image should be a content field rather of a style field.

Similarly, use style fields for presentational and stylistic elements. For example, borders or background images behind text, as they generally do not communicate meaning, and are not required to understand the page's content.

When it comes to considering using an image field or background image field, consider accessibility. If the content creator should have the ability to add alt text, use an image field instead of a background image field.

Organizing fields

How you organize your fields plays a large part in the content creator’s ability to quickly get in, make changes and get out.

  • Group style fields based on the component they control rather than the stylistic element. 
  • Leave only the highest-level, most important fields outside of groups.
    • Favor creating a component group over unnested groups. If you ever need to add functionality to your module later, you can't move your modules to a group later without manually updating all of the instances of the module on pages.
  • Order field groups in the order in which the components appear based on the primary language of the majority of the content creators that will be maintaining the site. Example: English is read from left to right, top to bottom. If the people maintaining the site typically read right to left in their language - then provide it right to left. When in doubt, base this off of the primary language of the content for your site.
  • Style fields should be in the group for the component they control.

Example: card module.

A typical card layout containing an icon, text, and a button. Styling options are shown grouped on the right into Icon, Button, and Card categories.

The styles panel groups the module fields into 3 groups based on components in the card that can be styled.

  • Icon
  • Button
  • Card

The color field for the icon would reside in the "Icon" group. A color field for the background color of the button, and a color field for the text color would exist within the "Button" group.

When viewing the card, the icon is seen first, then the text and button. The Icon group and it's styling options appear before the button group and it's styling options.

Required fields

Required fields are fields that are absolutely necessary to be set in order to display the module at all. 

  • Only require fields to have a value if it breaks the module to not have a value.
  • If you need to have a required field, provide a default value if possible. 

Example: Image carousel

Let’s say you’re building an image carousel module which allows you to configure how many slides display at the same time or per "page". A minimum value of 1 is needed, and without a value, you don't know how to display the image carousel. This is a situation where requiring a value, but setting a default value of one or two might make sense.


Since typographic styles can be controlled in the rich text field, you don't need to add specific style fields to control typography for content they contain. If you need to be able to provide typographic styles that apply across multiple pieces of content within the same module, that may be an exception. In that situation you may be able to make the content creator's work more efficient by providing font and color fields. In those situations, it is still a good idea to allow rich text field's typographic controls to override those style fields. If a style field does control a rich text field, it may be worthwhile setting help text, to ensure the content creator is aware.

Font Fields

Because rich text fields provide more typographical, and personalization controls along with a better ability to target specific ranges of words to apply styling to, we recommend using rich text fields over a combination of text field and font field when possible.

Field types and display types to use based on the use-case

Fields were meant to be able to cover a wide variety of controls you might want to offer. Some field types and some field display settings make more sense for specific use-cases.

Boolean fields

Boolean fields have two display styles. Toggle, and checkbox. 

A toggle is best used when the field controls a major design/layout change. Think: on/off situations, just like a light switch. For example, converting the layout of a card in a module from vertical to a horizontal orientation.

A checkbox is best suited for situations  when there are boolean fields that are less drastic in what they affect. For example,  hiding or showing a publish date for a blog post in a featured blog posts module.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.