Responsive layouting in AEM

Reading Time: 5 minutes

Responsive layouting allows you to add components inside a responsive grid which give you the ability to:

  1. Change the width of the component based on columns
  2. Push down a component
  3. Hide a component

All of the above can be done for a specific breakpoint (e.g. Phone, Tablet, Desktop). Also, you can specify custom breakpoints and emulators that will allow you to see how your page will look on multiple devices. Now we will show the steps necessary to enable responsive layouting in AEM.

Register your page components for emulation

We will be using "myapp" as a placeholder for the name of your application.

Create folder apps/myapp/config. Under that folder create a node with:
1. name:
2. jcr:primaryType: sling:OsgiConfig

Notice that we should specify an alias after

Then add properties:
1. Name: mobile.resourceTypes
2. Type: String[] (Multi)
3. Value: The paths to the page components that render your web pages. For example: myapp/foundation/components/page


Specify the device groups

Add the following property to the root page’s jcr:content node (e.g. /content/homepage/jcr:content) or it can be added to jcr:content node in the page’s template.
1. Name: cq:deviceGroups
2. Type: String[]
3. Value: /etc/mobile/groups/responsive


Link your site to the specified device groups

Include the following code in the JSP that defines the head section (or in the page-body.html of the base page):


In sightly it would be something like:



Configure the breakpoints

Using CRXDE Lite (or equivalent), navigate to either:
1. Your template definition.
2. The jcr:content node of your page.

Under jcr:content create the node:
1. Name: cq:responsive
2. Type: nt:unstructured

Under the cq:responsive node create the node:
1. Name: breakpoints
2. Type: nt:unstructured

Under the breakpoints node you can create any number of breakpoints. Each definition is a single node with the following properties:
1. Name: (descriptive name)
2. Type: nt:unstructured

Then add the following properties to the node
1. title: String (descriptive title seen in Emulator)
2. width: Decimal (value of breakpoint)



Replace parsys

Replace parsys with a responsive grid in the html sightly code and in the templates


Add the minimum css

Add the following less code to the design clientlib:

@import (once) "/etc/clientlibs/wcm/foundation/grid/grid_base.less";

/* maximum amount of grid cells to be provided */

@max_col: 12;

/* default breakpoint */

.aem-Grid {
  .generate-grid(default, @max_col);

/* phone breakpoint */

@media (max-width: 768px) {
  .aem-Grid {
    .generate-grid(phone, @max_col);

/* tablet breakpoint */

@media (min-width: 769px) and (max-width: 1200px) {
  .aem-Grid {
    .generate-grid(tablet, @max_col);


Now, add code for your breakpoint. For example, if your breakpoint is called “Test” then you should add the something like this:

/* test breakpoint */
@media (max-width: 950px) {
  .aem-Grid {
    .generate-grid(test, @max_col);

Create a custom mobile emulator

To create a custom mobile emulator you have two options. The first one is to follow these instructions:

  1. Below /apps/myapp/components/emulators create the component with the name you want e.g. “myemulator” (node type:cq:Component).
  2. Set the sling:resourceSuperType property to /libs/wcm/mobile/components/emulators/base
  3. Define a CSS client library with category for the emulator appearance: name =css, node type = cq:ClientLibrary
  4. As an example, you can refer to the node /libs/wcm/mobile/components/emulators/iPhone/css
  5. If needed, define a JS client library, for example to define a specific plugin: name = js, node type = cq:ClientLibrary. As an example, you can refer to the node /libs/wcm/mobile/components/emulators/base/js
  6. If the emulator supports specific functionalities defined by plugins (like touch scrolling), create a configuration node below the emulator: name = cq:emulatorConfig, node type = nt:unstructured and add the property that defines the plugin:
  7. Name = canRotate, Type = Boolean, Value = true to include the rotation functionality.
  8. Name = touchScrolling, Type = Boolean, Value = true to include the touch scrolling functionality.
  9. More functionalities can be added by defining your own plugins.

The second and easier option is to copy the emulator of the iPhone4 (it is the most complete) located in libs/wcm/mobile/components/emulators/ios/iphone4 and copy it in the /apps/myapp/components/emulators folder you created.


Then modify the css in css/source/emulator.css by replacing the “iphone4” string with the name of the custom emulator.


Then add the emulator in http://localhost:4502/etc/mobile/groups/responsive.html. First select “Edit” then click on the tab “Emulators”. After that click on “Add item”. Finally, select your newly created emulator in the dropdown.


On the cq:emulatorConfig node the height and width corresponds to the double of the value shown in the emulator. So if you emulator is 1200px wide you should set the “width” value to 2400. The same applies for the “height” value.


If the emulators are made with the exact value of the breakpoints, then the breakpoint markers in the emulation bar will not appear as activated. In that case you can make the emulators 1 pixel smaller. For example, if you have a 1200px wide breakpoint then your emulator width should be 2398px wide ((1200 - 1) * 2).

We hope this tutorial has helped you understand how to use responsive layouting within AEM. Thank you for reading!

You May Also Like