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.

How can we provide a better experience?

HubSpot provides its own modules and default themes. We realized quickly we had to establish some best practices. Internally at HubSpot, we've created a guide to how we will be integrating style fields with our own modules moving forward. We're releasing parts of it out to you in the hopes that we can establish a standard for organizing styling options.

We're going to use some language in this guide that refers primarily to design and may not be used elsewhere in our documentation. This is what we mean when we say the following terms:

  • Component - This is a smaller piece of a module. 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 - this refers to 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 - this refers to the boolean field's ability to be displayed as a toggle switch (think light-switch).
  • Text and image module - this is simply referring to a common design where an image will be placed next to each other horizontally.

When to use style fields and when to use content fields

Style fields show in the styles tab. They are intentionally separated from the module fields you provide in the content tab. Maintaining this separation gives content creators a clear, easy, and consistent way to quickly build out their content.

  • Avoid using a style field for conveying meaning or context that the website visitor requires to understand the content. For example, If you have a text and image module - and the image is required or potentially required in order to understand the text content - then do not use a style field.
  • Use style fields for presentational and stylistic elements.Background images behind text are a good example. Other examples include borders, or colored backgrounds - they generally do not communicate meaning, and are not required to understand what the text is about.


alignment and spacing fields in an image module

Content fields should be used for content that provides meaning, and style fields should be used to control appearance.

When it comes to considering image fields vs. background image fields, think in terms of accessibility. If the content creator should have the ability to add alt text - use an 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 page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.