Decoration Tag (cq:htmlTag)#

When AEM includes a component on a page, it wraps the component's own output in an extra HTML element called the decoration tag. This is the element you see around your markup with a class that matches the component name, for example:

<div class="text aem-GridColumn aem-GridColumn--default--12">
  <!-- the component's own HTL output starts here -->
  <div class="cmp-text">...</div>
</div>

The outer <div class="text ..."> is not produced by your HTL. AEM's decoration mechanism adds it so the authoring UI (drag handles, the responsive grid, in-place editing) has a stable element to hook into, and so layout/grid classes have somewhere to live.

cq:htmlTag is the component node that lets you control what that decoration element looks like - which HTML tag it uses and which attributes (most importantly class) it carries.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
          xmlns:cq="http://www.day.com/jcr/cq/1.0"
          jcr:primaryType="nt:unstructured"
          cq:tagName="section"
          class="my-text-wrapper"/>

text/
├── .content.xml          # cq:Component
├── _cq_dialog/
│   └── .content.xml
├── _cq_htmlTag/          # the decoration tag node
│   └── .content.xml
└── text.html             # HTL

#When it is helpful

#Semantic HTML wrappers

The default div is rarely the most meaningful element. Use cq:tagName to emit landmark or list elements so the rendered page is more semantic and accessible - without polluting your HTL with the wrapper.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="nt:unstructured"
          cq:tagName="li"
          class="nav__item"/>

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="nt:unstructured"
          cq:tagName="section"
          class="promo"
          role="region"/>

#A stable styling hook

When your CSS or BEM convention needs a reliable wrapper class on the decoration element (rather than only on the inner markup your HTL controls), cq:htmlTag gives you one place to declare it.

#Overriding classes inherited from a supertype

This is the most common "gotcha" worth knowing. When a component sets sling:resourceSuperType to a core component, it inherits that core component's cq:htmlTag. The Core Components add their own classes this way - for example the Experience Fragment component contributes an experiencefragment class to the decoration element.

If you extend such a component but want a different (or no) extra class, declare a local _cq_htmlTag. A local decoration-tag node shadows the inherited one entirely:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
          xmlns:cq="http://www.day.com/jcr/cq/1.0"
          xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="cq:Component"
          jcr:title="Richtext XF Reference"
          sling:resourceSuperType="core/wcm/components/experiencefragment/v2/experiencefragment"/>

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="nt:unstructured"
          class="richtext"/>

Result: the inherited experiencefragment class is gone and richtext is used instead, so the wrapper lines up with a plain richtext component's wrapper for styling purposes:

<!-- before: inherited class -->
<div class="richtext-xf-reference experiencefragment">...</div>

<!-- after: local _cq_htmlTag with class="richtext" -->
<div class="richtext-xf-reference richtext">...</div>

#Disabling or overriding decoration at include time

cq:htmlTag configures decoration per component. You can also control it per include from HTL, which is useful when the same component should be wrapped differently in different contexts (or not at all).

<sly data-sly-resource="${ 'content' @
    resourceType='myproject/components/text',
    decorationTagName='article',
    cssClassName='featured' }"></sly>

<sly data-sly-resource="${ 'content' @
    resourceType='myproject/components/text',
    decorationTagName='' }"></sly>

#Gotchas

• It adds, it does not replace. class on cq:htmlTag is merged with the component name and grid classes.
• Inheritance shadows, it does not merge. A local _cq_htmlTag replaces the inherited one wholesale; you do not get a union of inherited and local properties.
• cssClassName vs cq:htmlTag. The cssClassName include option and the design-dialog Style System add classes at a different layer than cq:htmlTag; reach for cq:htmlTag for static, code-owned defaults and the Style System for author-selectable styles.
• Empty wrappers disappear. If the component produces no markup, AEM drops the decoration element, so do not rely on it always being present in the DOM.

#References

• Decoration Tag (Experience League, AEM 6.5)
• HTL Templates (Sightly) - data-sly-resource and include options
• Templates and Policies - the Style System and policy-driven CSS classes