Understanding How to Use the AEM Grid

Learn best practices for layout containers and why they’re not a replacement for responsive frameworks.

Tiffany Olejnik
May 30 · 6 min read

There isn’t a single client that doesn’t have responsive requirements as part of their site experience. Confusion around how these requirements translate to Adobe Experience Manager tend to surface when discussions for what can or cannot be provided OOTB and where the UI development for it comes into play. Brand guidelines typically have a specified set of breakpoints based on customer audiences and key channels, and need to stay true to that set definition. Here, we’ll solve a few misconceptions on how marketers can leverage what AEM Grid provides and how to adapt it to their own customization needs.

“What exactly IS the AEM Grid and how can content authors use it?”

The AEM Grid is actually the stylesheet for the responsive grid system, which is part of the Layout Container component. The Layout Container allows content authors to add and position components within that responsive grid. The Layout Container can be configured as a component to be dropped onto a page, or as the default component drop area on an Editable Template. The author can then use Layout Mode to specify the responsive behavior such as the span of columns desired, hide or show content for specific breakpoints, and then preview that breakpoint for devices such as Samsung or iPhone screen sizes.

Adobe HelpX already has excellent documentation on how to use the Layout Mode to create responsive layouts and preview on various device sizes.

A common misconception is that AEM Grid / Layout Container is meant to replace any responsive framework — this is not the case. While the AEM Grid stylesheet can be used in lieu of third-party responsive grid frameworks, there are a few caveats in how it functions. The AEM grid was designed for “responsive authoring” — where the author can manage the layout and flow of content without being dependent on development workflows. Some components may need to be independent of responsive authoring, such as a header or footer, and front-end developers will still need to leverage their own responsive framework (mentioned below).

The AEM Grid for responsive authoring also follows a very specific isolated breakpoints approach. This means, the AEM Grid is not a mobile-first structure, and by this, provides the benefit for an author to target a single segment of screen sizes. This is designed so authors can tailor and configure components for each individual breakpoint without affecting another. Authors will potentially need to manually configure components on each break point size, giving them full control over how that responsive behavior functions.

“But how can the AEM grid be customized if it does not meet our needs?”

The ideal best practice is to use the AEM Grid for author responsive layouting (as part of the layout container) and any outside responsive framework for styling components. This can provide front-end developers the ability to take advantage of flex box to manage the responsive behavior for specific components without taking away template layout flexibility for authors. Although, there may be cases where the default AEM Grid breakpoints do not meet your needs. In order to align your responsive authoring with your style guide’s provided breakpoints, you’ll need to customize the AEM Grid stylesheet file.

The AEM Grid uses three breakpoints for a 12-column grid. There is a default breakpoint that covers all sizes (which could also be seen as a desktop-first approach), a phone breakpoint which spans the smallest size to a maximum width of 768px, and a tablet breakpoint that spans a minimum width of 769px to a maximum width of 1200px. These values can be found in the grid.less file in AEM which will need to be modified by your front-end developer.

Here is a sample of the grid.less file that front-end developers can use to customize the breakpoints available for authors in AEM’s Layout Mode feature.

@import (once) "grid_base.less";@max_col: 12; /* maximum amount of grid cells *//* 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);

Front-end developers are able to make any media query value modifications they may need to the grid.less file, but should not make changes to the established class names. It should be also noted that any customizations made should be clear to the authors so they understand the changes that impact their page creation workflow.

Adobe provides GitHub documentation of the responsive grid as a reference for front-end developers to create sample static pages to mock-up prior to the AEM back-end implementation. This sample version of the AEM grid classes and HTML structure allows them to easily create the same responsive layouting that is in AEM.

“So, why can’t I just use Bootstrap instead?”

As noted previously, Bootstrap can be used in addition to the AEM Grid for components that do not need responsive authoring capabilities, but the AEM Grid cannot be outright replaced with Bootstrap or other responsive frameworks.

The class names generated for the AEM Grid are tied directly to the Layout Container functionality in AEM. Advanced features of Editable Templates, such as policies for allowed components, the style system, or defined initial content, strictly rely on the Layout Container and Layout Mode — which is tied into the AEM Editor. So significantly extending the Layout Container itself can break this functionality and make it more difficult to upgrade in the future. While the grid.less file can be updated to reflect your defined breakpoints, the class names cannot be changed to adopt outside frameworks.

The AEM Grid and Layout Container is an OOTB feature, so these modifications could also pose a problem if Adobe Support is needed for any related issues or Feature Pack updates are made in the future. If there is concern over responsive layout governance, it is recommended to discuss the Template Editor role and where flexibility is expected between the UX team and content authors.

The AEM Grid operates in close proximity to how the Bootstrap grid does. Both use customizable column count and nesting. While, Bootstrap v4 uses Flexbox and SASS, AEM Grid uses CSS floats and LESS (which also supports legacy browsers). However, Bootstrap components will still work within the AEM Grid with the intended component flexibility. Bootstrap components are developed in a fluid way where the responsive layouting is not defined within the component code itself, but handled by the parent container.

The Layout Container component is a powerful tool for enabling content authors with the ability to visually see and adjust the responsive layout, which used to strictly be a developer task. Using the AEM Grid for authoring responsive layouts and 3rd party responsive framework for styling components will also allow front-end developers the ability to take advantage of flex box without taking away template layout flexibility for authors. While this approach gives you the ultimate flexibility for both your content authors and front-end developers, make sure to align your roles and responsibilities, especially when it comes to defining editable templates.

Stay tuned as I look to share more about governance in world of UX and content authors for using editable templates and how to customize the AEM Grid to work with Bootstrap! Check out the AEM Grid Part II article on Customizing the AEM Grid.

Follow the Adobe Tech Blog for more developer stories and resources, and check out Adobe Developers on Twitter for the latest news and developer products.

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers, and technology.

Tiffany Olejnik

Written by

Senior AEM Consultant at Adobe. Focused on UX and Front-end Development.

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers, and technology.