AEM Components Overview#

An AEM component is a self-contained building block that authors drag onto a page, configure via a dialog, and that renders HTML through an HTL template backed by a Sling Model. Every component instance is stored as a JCR node under the page's jcr:content tree, and its sling:resourceType property tells Sling which rendering scripts to use.

#Component Types

#Component Anatomy

Every component consists of up to five artifacts:

myproject/components/articlecard/
  .content.xml                    1. Component definition (resourceType, group, superType)
  articlecard.html                2. HTL template (view)
  _cq_dialog/.content.xml        3. Author dialog (per-instance fields)
  _cq_design_dialog/.content.xml 4. Design dialog (template policy fields)
  clientlibs/                     5. Clientlibs (CSS/JS for authoring and runtime)

The Sling Model (Java) lives in the core/ module and is connected via data-sly-use in the HTL template.

For a complete step-by-step walkthrough of building all five artifacts, see the Custom Component Guide.

#Component Lifecycle

What happens when an author uses a component:

#Style System

The Style System allows template authors to define CSS class combinations that content authors can apply to components without developer involvement. This enables visual variations (e.g. "Hero - Dark", "Hero - Compact") from a single component.

#Configuring in template policies

1. Open the Template Editor for your template
2. Select a component and click the policy icon
3. Under the Styles tab, add style groups and options:

• Group: "Layout" - options: "Default", "Compact", "Wide"
• Group: "Theme" - options: "Light", "Dark"

4. Each option maps to one or more CSS classes (e.g. cmp-hero--dark)

When an author selects a style, AEM adds the CSS classes to the component's wrapper element.

#Reading style values in a Sling Model

If you need to vary server-side logic based on the applied style (not just CSS), you can read the current style programmatically:

import com.adobe.cq.wcm.style.ComponentStyleInfo;

// Adapt the component's resource to ComponentStyleInfo
ComponentStyleInfo styleInfo = request.getResource().adaptTo(ComponentStyleInfo.class);

if (styleInfo != null) {
    // Get the applied CSS classes as a space-separated string
    String appliedClasses = styleInfo.getAppliedCssClasses();

    // Check for a specific variation
    boolean isDark = appliedClasses != null && appliedClasses.contains("cmp-hero--dark");
}

ComponentStyleInfo provides:

#BEM naming convention

Follow the BEM convention for component CSS classes. This aligns with how AEM Core Components name their classes:

.cmp-hero                    Block
.cmp-hero__image             Element
.cmp-hero--dark              Modifier (applied via Style System)
.cmp-hero__title--large      Element + Modifier

The cmp- prefix is the Core Components convention. Use your own project prefix if you prefer (e.g. myp-hero), but be consistent across all components.

#Extending vs Building from Scratch

For extending and merging Core Component dialogs, see Core Components.

#Component Groups and Allowed Components

#Component groups

The componentGroup property in .content.xml controls where the component appears in the editor's component browser:

componentGroup="My Project - Content"

Common group naming patterns:

• My Project - Content - general content components
• My Project - Structure - structural components (header, footer)
• My Project - Commerce - commerce-specific components
• .hidden - hides the component from the browser (still usable via policies)

#Allowed components via template policies

In the Template Editor, click the policy icon on any container to configure which component groups (and individual components) are allowed in that container. This is stored under /conf/myproject/settings/wcm/policies/.

#Quick Reference