which hubl tags are deprecated in hubspot (and what replaces them)
by josh ozuna · codefmt
published June 11, 2026
HubSpot has deprecated five HubL tags, all from the era before widgets became modules: widget and custom_widget (replaced by module), widget_block (replaced by module_block), widget_attribute (replaced by module_attribute), and widget_container (replaced by dnd_area). paste a template into the codefmt HubL linter and the hubl/deprecated-tag rule flags every one, with a one-click fix that swaps in the replacement.
every deprecated tag and its replacement
| deprecated tag | use instead | notes |
|---|---|---|
widget | module | the original name for a standard module tag |
custom_widget | module | custom and standard widgets unified under module |
widget_block | module_block | block-syntax module with inline parameters |
widget_attribute | module_attribute | parameter overrides inside a module_block |
widget_container | dnd_area | flexible columns replaced by drag-and-drop areas |
the replacements are documented in HubSpot's own references: standard HubL tags for the module family and drag-and-drop areas for dnd_area.
why deprecated tags linger in old themes
templates that use the widget-era tags can still render, so nothing forces a migration and the legacy syntax survives copy-paste from theme to theme. the cost shows up later: new teammates learn tag names the docs no longer teach, and the markup drifts further from what HubSpot's current tooling and examples assume. since each replacement is a rename of the same tag shape, migrating is cheap compared to almost any other cleanup.
how the linter flags them
codefmt's hubl/deprecated-tag rule checks every tag against the deprecation catalog and reports a warning in the form 'widget' is deprecated. Use 'module' instead. each finding ships a safe auto-fix, so the Fixbutton replaces the tag name in place without touching parameters or surrounding markup. it's one of the seven rules with one-click safe fixes in the rule reference.
- copy a template or module out of the design manager and paste it into the HubL formatter and linter.
- each deprecated tag shows as a warning with the replacement named in the message.
- click
Fixto apply the renames, then copy the migrated template back into HubSpot.
deprecation goes beyond tags
tags are the part the linter auto-fixes today, but HubSpot's deprecation docs also cover legacy filters and functions: include_css and include_javascript gave way to require_css and require_js, and blog topics became tags (blog_topics to blog_tags). while you're cleaning up a theme, sweep for those too. for everything else the 28 rules catch, from unclosed blocks to unknown filters, see the HubSpot CMS linter guide.
frequently asked questions
which hubl tags are deprecated?
five legacy tags: widget (use module), custom_widget (use module), widget_block (use module_block), widget_attribute (use module_attribute), and widget_container (use dnd_area). they date from before HubSpot renamed widgets to modules and introduced drag-and-drop areas.
do deprecated hubl tags still work?
templates using them can still render, which is why they linger in older themes for years. but they're legacy syntax on borrowed time: new development should use the module and dnd_area equivalents, and migrating now is a rename rather than a rewrite.
how do i find deprecated tags in my templates?
paste the template into the codefmt HubL linter. the hubl/deprecated-tag rule flags each legacy tag as a warning, names the replacement, and ships a one-click safe fix that swaps the tag name in place.
are any hubl filters or functions deprecated too?
yes. HubSpot's deprecation docs also list legacy filters and functions, like include_css and include_javascript (replaced by require_css and require_js) and blog_topics (replaced by blog_tags). the dedicated deprecation page on developers.hubspot.com tracks the full list.
primary source: HubSpot: HubL syntax reference