Developing Core Components

Last update: 2023-03-10
  • Created for:
  • Developer

When to Use the Core Components?

As the Core Components are all-new, and offer multiple benefits, it is recommended for new AEM projects to use them. For existing projects, a migration should be part of a larger project effort, for example a rebranding or overall refactoring.

Therefore, Adobe provides following recommendations:

  • New Projects
    New projects should always attempt to use Core Components. If Core Components cannot be used directly or extended to satisfy project requirements, then create a custom component following the component architecture set forth in core components. Except where not otherwise possible, avoid using the foundation components.
  • Existing Projects
    Recommendation is keep using the foundation components, unless a site or component refactoring is planned.
    As they are very widely used by most existing projects, the foundation components will continue to be supported.
  • New Custom Components
    Assess if an existing Core Component may be customized.
    If not, recommendation is to build a new custom component following the Component Guidelines.
  • Existing Custom Components
    If your components work as expected, then keep them as they are.
    If not, refer to “New Custom Components” above.

How to Succeed with the Core Components

The Core Components are powerful, flexible, and easy to use and customize. Following a few key guidelines will ensure that your project with the Core Components is a success.

Migrating to the Core Components

Any new project should be implemented with Core Components. However existing projects will usually have extensive implementations of the Foundation Components.

Migrating from Foundation Components

A larger effort on an existing project (for example a rebranding or overall refactoring) often offers a chance to migrate to the Core Components. To facilitate this migration, Adobe has provided a number of migration tools to encourage the adoption of the Core Components and the latest AEM technology.

The AEM Modernization Tools allow for the easy conversion of:

  • Static templates to editable templates
  • Design configurations to policies
  • Foundation Components to Core Components
  • Classic UI to Touch-Enabled UI

For further information about the usage of these tools, see their documentation.


The AEM Modernize Tools are a community effort and are not supported or warrantied by Adobe.

Migration via Move to AEM as a Cloud Service

Because AEM as a Cloud Service comes with the latest version of the Core Components automatically, when you move from an on-premises AEM installation, you will need to remove any dependency to the Core Components in your projects pom.xml file.

Your proxy components will still work as they did before because proxies point to the necessary supertype and the supertype path has the version in it. In this way, simply removing the dependency enables the Core Components to work in AEMaaCS just as they did on-premises.

Just like any other AEMaaCS project you will also need to add a dependency to the AEM SDK jar as well. This is not specific to the Core Components, but is required.


See the document AEM Project Structure for more information about AEMaaCS projects.

Core Component Support

Core Components are an integral part of AEM and supported as is, under the same terms and conditions as if they were delivered as part of the Quickstart.

Like other AEM product features, the general rule is: Components are first announced to be deprecated, and the earliest removed for the following AEM release. That gives customers at least one release cycle to move to the new version of the component, before dropping its support.

The version of each component clearly states the AEM versions that it supports. When support ceases for a version of AEM, then so does the support of the Core Components for that version of AEM.

For details about the support of component customizations, see the Customizing Core Components page.

Technical Capabilities

The following table gives an overview of the differences between core components and foundation components.

For details about their authoring capabilities and options to pre-configurable them, refer to the authoring page about them.

Capability Core Component Foundation Component
Logic implementation Java POJOs with Sling Models annotations JSP code
Markup definition HTML Template Language (HTL) syntax JSP code
XSS sanitization Automated by HTL Mostly manual
CSS classes naming Standardized naming convention based on Block Element Modifier (BEM) notation (as of release 2.0.0) Custom schemes
Dialog definition Coral 3 Coral 2 + Classic UI
JSON output Sling Models Exporter with Jackson serialization Default Sling servlet
Versioning For the model and the HTL None
Testing Unit Tests + Integration Tests Integration Tests
Delivery Via public GitHub Via Quickstart
License Apache License Adobe proprietary
Contribution Via pull request Not possible
Accessibility Fully compliant with the WCAG 2.0 AA standard Only partially compliant with the WCAG 2.0 AA standard

Component List

The following table lists the available Core Components, linking to their API, and indicates which foundation components they replace.

Core Component Description Replaced Foundation Component(s)
Page Responsive page working with template editor /libs/foundation/components/page /libs/wcm/foundation/components/page
Breadcrumb Page hierarchy navigation /libs/foundation/components/breadcrumb
Title H1-H6 title /libs/foundation/components/title /libs/wcm/foundation/components/title
Text Rich text /libs/foundation/components/text /libs/foundation/components/table /libs/wcm/foundation/components/text
Image Smart and lazy loading of optimal rendition size /libs/foundation/components/image /libs/foundation/components/adaptiveimage /libs/foundation/components/logo /libs/foundation/components/mobileimage /libs/foundation/components/mobilelogo /libs/wcm/foundation/components/image
List List of pages /libs/foundation/components/list /libs/foundation/components/mobilelist /libs/wcm/foundation/components/list
Social Media Sharing Facebook and Pinterest sharing widget -
Form Container Responsive form paragraph system /libs/foundation/components/form/start /libs/foundation/components/form/end
Form Text Text input field /libs/foundation/components/form/text /libs/foundation/components/form/password
Form Options Multiple options input field /libs/foundation/components/form/checkbox /libs/foundation/components/form/radio /libs/foundation/components/form/dropdown
Form Hidden Hidden input field /libs/foundation/components/form/hidden
Form Button Submit or custom button /libs/foundation/components/form/submit
Navigation A site navigation component that lists the nested page hierarchy /libs/foundation/components/topnav /libs/foundation/components/mobiletopnav
Language Navigation A language and country switcher that lists the global language structure -
Quick Search A search component that displays the results as in-place suggestions in a drop-down menu /libs/foundation/components/search
Teaser Allows the content author to easily create a teaser to further content using an image, title, or rich text and linking to further content or other actions -
Tabs Allows the content author to organize page content within multiple tabs -
Carousel Allows the content author to organize content in a rotating carousel of slides /libs/foundation/components/carousel
Content Fragment Allows for the display of a content fragment -
Content Fragment List Allows for the display a list of content fragments -
Separator Separates content on a page -
Accordion Organize content panels in a collapsible accordion -
Container Organize components within a container -
Button Create a button on a page -
Download Add a downloadable asset to a page -
Experience Fragment Add an experience fragment to a page /libs/cq/experience-fragments/editor/components/experiencefragment
Embed Embed an external resource within a page -
Progress Bar Provide a visual representation of progress towards a goal -
PDF Viewer Presents a PDF document on a page -

Upgrade of Core Components

One benefit of versioned components is that it allows to separate the migration to a new AEM version from the migration to new component versions. Also, if new component versions are available, it allows for the individual migration of each component to the new version.

Migrations to a new AEM version won’t impact how the Core Components work, provided that their versions also support the new AEM version that is being migrated to. Customizations made to the Core Components should not be affected either, as long as they don’t use APIs that have been deprecated or removed.

Migrations to new versions of the Core Components won’t impact how the component works either, but new features might be introduced to page authors, which might require some configuration by a template editor, in case the default behavior isn’t desired. Customizations however might need to be adapted, for more details see the Customizing Core Components page.

On this page