Drag and Drop Areas overview

Last updated:

Drag and drop areas enable you to create areas of pages and global partials that empower content creators. Drag and drop areas allow content creators to place modules, change layout, and some styling within the content editors. This enables you to create fewer templates, as content creators can create layouts on their own. 

This page illustrates and explains the dnd_area experience and concepts. Once you're ready to build, see getting started with dnd_area, and the dnd_area reference.

Please note: drag and drop areas can't be used in blog post, and email templates.

The content creator experience

When a content creator creates a page using a template that has drag and drop areas they first see the page with predefined modules placed in a layout by the developer. This helps to illustrate how visually most pages using this template should or tend to look. Using drag and drop areas, the content creator can then build the page, including:

  • Add modules, sections, rows, and columns
  • Resize modules and update their content and styling, such as adjusting alignment and adding backgrounds

This gives content creators enough flexibility to make simple  page changes without needing a developer for small tweaks.

Please note: a content creator can swap a page's template for another template of the same type, depending on whether it has dnd_area tags.

  • Templates built with the visual drag and drop layout editor can be swapped for other drag and drop templates or coded templates with or without dnd_area tags.
  • Coded templates with dnd_area tags can only be swapped for other coded templates with dnd_area tags.
  • Coded templates without dnd_area tags can only be swapped for other coded templates without dnd_area tags.
The page editor experience for dnd_areas

The developer experience

Working with drag and drop areas is semi-similar to working with common CSS frameworks and their grids. First you'll lay out the page using containers, called sections, which contain rows. Inside of those rows are modules and columns.

Nearly everything that content creators can do in the page editor with drag and drop area tags, developers can do in code in the templates themselves. However, what you as a developer are building is the default content for pages using that template.

View the CMS Theme Boilerplate templates to see dnd_area tags in use.

dnd_area coded in VS Code

Drag and drop areas and their elements

Drag and drop areas consist of building blocks that define the layout and support styling alignment flexibility. The dnd_area tag creates a region in the page that the page editor recognizes, enabling adding, removing, and rearranging of drag and drop elements. You define these using HubL inside of HTML+HubL templates. All of the drag and drop elements live inside of a drag and drop area. You cannot nest drag and drop areas, and drag and drop elements cannot contain drag and drop areas themselves. 

An important thing to understand as developers is that the contents of the drag and drop area  you define in the template, is a starting point for pages using that template. Content creators can completely change the content within a drag and drop area. Your job is to provide a sane starting point for them to modify from.

Example structure

This diagram is a breakdown of how the various drag and drop elements can be nested. A key concept to understand is that both sections and rows can contain columns and modules.

Drag and Drop element relationships


Sections are a special type of row. Sections are created in templates using the dnd_section tag. They are the only drag and drop element that can be a direct descendant of a drag and drop area. You can think of sections like an outer wrapping container. They can enable content to be full width or have a confined center max width. Because sections wrap around columns and modules, it makes it easy to rearrange and implement large portions of content. The dnd_section tag does not render an HTML <section> element.

Section in page editor

The appearance of a section in the page editor.

Developers can provide section templates - which create reusable sections in the page editor. These are pre-configured sections defined by the developer, that content creators can use as a starting point. Reusable sections have some unique capabilities, including being able to use them similar to a standard hubL template partial.


Columns are wrappers for rows and modules. You place columns inside of a row, or section which is a specialized row. Columns are created in templates using the dnd_column tag.

Use multiple columns inside of a row to place rows and the modules they contain horizontally. 

Columns are vertical regions that can contain rows. You can make columns of different sizes by changing their width. A row’s size is 12 "columns" wide, this refers to the CSS grid. The columns inside of a row can be any size smaller than 12 but cannot add up to more than 12.

When multiple rows are placed inside of a column the modules inside of those rows will appear vertically stacked. Since modules are columns themselves, a module cannot be a direct descendant of a column, they must be contained within a row.

dnd_area column in page editor

The appearance of a column in the page editor.


Rows are wrappers for columns. Rows are created in templates using the dnd_row tag. Since modules are columns you can place them directly inside of a row. This will cause the modules to appear horizontally adjacent to each other.

Modules can be organized vertically by placing them inside of rows. If you want to place a module above another you would place that module inside a row. You would then add another module in a row above or below that first row. 

dnd_area row in page editor

The appearance of a row in the page editor.


Modules are a fundamental part of the HubSpot CMS, acting as reusable building blocks that you use to piece together a site, and display content. When building a template you place modules inside of drag and drop rows and sections using the dnd_module tag. Modules are also columns. Meaning if you place two module tags, or a module and a column directly next to each other, they will appear side-by-side horizontally. 

No drag and drop elements can be placed within a module. Modules cannot be direct children of a dnd_area.

HTML structure and styling

Drag and drop areas and their elements when rendered have class names for a 12 column grid based on bootstrap 2. To make it easy to get up and running, you can use the _layout.css file from the CMS Theme Boilerplate. This provides default styles for those class names. 

You are not required to use this stylesheet and can provide your own styles instead. If you are building your site based off of the CMS Theme Boilerplate and want to use your own CSS, you will want to remove layout.css from being called in base.html. For your own CSS grid you will need to target those same grid class names, but the styling is up to you.

Drag and drop areas when rendered create divs with classes that are used by the page editor. Examples would be widget-span and widget-type-cell. You should not directly target these classes as they are used by page-editor and could change down the road.

Instead in your dnd_area HubL add a class parameter with a class name you would like to use

<div class="container-fluid my-custom-class"> <div class="row-fluid-wrapper"> <div class="row-fluid"> <div class="span12 widget-span widget-type-cell " style="" data-widget-type="cell" data-x="0" data-w="12"> </div> <!--end widget-span --> </div> </div> </div>

Editor and attribute styling

With drag and drop areas content creators can have some effect on styling of the page. For example they can set a section to have a background. Developers can pass default values for those settings through attributes.

When the page is actually rendered, the styles that are generated based on those settings is added to the standard_header_includes.

At launch of dnd_area those styles were loaded from standard_footer_includes. That was changed recently to standard_header_includes and is rolling out to all HubSpot accounts with the HubSpot CMS.


If you are changing templates built with flexible columns to now use drag and drop areas there's a few things you should understand. Flexible columns are not the same as drag and drop areas, you can't swap from a template that only has a flex column to one that only has a drag and drop area. We don't allow this as a safety precaution. The content would not map from the flex column to the drag and drop area. To illustrate why this is, suppose you built your new template so you have a sidebar and a main content area. Your sidebar is a flexible column, your main content is a drag and drop area. The swapping tool would map the flexible column to the flexible column.

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