When a GitHub Repository Stops You in Your Tracks
There are moments in a developer's life when you stumble across something on GitHub and your immediate, instinctive reaction is: "Wait - this should already exist everywhere." That was precisely my reaction when I landed on the official Sitecore Labs repository for the Layout Container component for XM Cloud.
If you work with Sitecore XM Cloud and Headless SXA, you will recognize the pain almost instantly. Your content authors want freedom, they want to build rich, multi-column, responsive page layouts without raising a development ticket. Your developers want to deliver clean, maintainable frontend code without copy-pasting bespoke wrapper <div> hierarchies all over the codebase. Your architects want a composable, reusable structural primitive that the entire team can rally around. And yet, out of the box, the XM Cloud Starter Kit leaves you to solve all of that yourself.
Enter the Layout Container - a deceptively simple name for a component that carries enormous potential. Built and published by the Sitecore Labs team (the same group that maintains the xmcloud-foundation-head starter kit and other first-party accelerators), this single component quietly addresses one of the most common friction points in any Headless SXA project: how do you give content authors meaningful layout control without handing them a blank canvas and a prayer?
What makes it truly exciting is what I'd call its universality. Unlike a "Hero" or a "Promo" component - which solves one specific presentational problem - the Layout Container is infrastructure. It is the scaffolding upon which every other component lives. Its scope is not a feature; it is a fundamental authoring primitive, and discovering it tucked away in a labs repository rather than shipped as a platform default is both a delight and, as we'll discuss, a genuine head-scratcher.
Let's dig into what this component actually does and why it matters so much.
Inside the Codebase - What Makes the Layout Container "Universal"
The repository is refreshingly lean. Its footprint consists of a LayoutContainer.tsx React/TypeScript component, a dedicated SCSS stylesheet folder, and a set of Sitecore-serialized content items that wire everything together on the Content Management side. That austerity is intentional - this is a utility component, and utility components should not carry unnecessary weight. But don't let the simplicity fool you: the architectural thinking behind it is substantial.
The Sitecore Item Architecture
The Sitecore side of the component is serialized using the Sitecore CLI (dotnet sitecore ser push) and lives under the familiar Headless Experience Accelerator rendering path: /sitecore/layout/Renderings/Feature/Headless Experience Accelerator/Layout Container.
This placement is deliberate and telling. By living under the Feature layer of the HEA namespace, right alongside the out-of-the-box Page Content components - the Layout Container is explicitly designed to behave as a peer to first-party SXA components, not a bolted-on afterthought. It is enabled through the site's Available Renderings configuration under the Page Structure group, which is exactly where structural components belong. This tells content authors unambiguously: "This component organizes other components. It is not content itself."
The module definition (layoutcontainer.module.json) follows the standard Sitecore CLI module pattern, meaning it integrates cleanly with existing serialization workflows. There is no custom build step, no exotic dependency, and no configuration magic required - just a clean dotnet sitecore ser push -i LayoutContainer and you are live.
The React Component: Flexibility Through Parameters
The heart of the component is LayoutContainer.tsx, a Next.js/React component following the canonical Headless SXA pattern that every XM Cloud developer will recognize:
type LayoutContainerProps = {
params: { [key: string]: string };
fields?: { [key: string]: Field };
};
This signature is significant. The heavy lifting in this component happens through params - the rendering parameters, rather than through datasource fields. This is the correct architectural choice for a structural component. Layout decisions (column count, spacing, background color, alignment) are rendering concerns, not content concerns. Using params instead of a datasource means the Layout Container does not pollute the content tree with structural data items, keeping the authoring experience clean and the content model honest.
The component dynamically assembles its CSS class list by composing values from its rendering parameters - including the built-in GridParameters that Headless SXA passes to every component. This means it inherits the full grid vocabulary of the SXA grid system right out of the box, without needing to reinvent it.
SCSS Architecture - Responsive by Design
The SCSS module (layout-container/) follows the same BEM-influenced, SCSS-variable-driven conventions used in the XM Cloud Starter Kit, making it trivially easy to integrate with an existing project's design token system. Rather than hardcoding breakpoint values or pixel measurements, the styles are structured to compose with the host project's existing _variables.scss and _mixins.scss infrastructure.
More importantly, the CSS is structured around CSS Grid and Flexbox semantics, giving it the full power of the modern layout cascade. This means:
- Column configurations (halves, thirds, quarters, asymmetric splits) are expressed as CSS Grid template columns, which adapt naturally to content reflow.
- Vertical stacking on mobile is handled via media query breakpoints that collapse multi-column grids to a single-column layout - no JavaScript required, no layout shift.
- Gap/spacing control maps to CSS
gap properties, keeping spacing consistent with the browser's natural rendering model.
The upshot is a component whose visual output is responsive, accessible, and performant - not because of clever JavaScript, but because it leans on what CSS is already brilliant at.
Component Nesting: The Real Superpower
If you've been reading this and thinking "okay, it's a grid wrapper - so what?" - this is the part that should change your mind.
The Layout Container is designed to be infinitely nestable, both with itself and with any other Sitecore component. In XM Cloud Pages, because it appears in the Page Structure available renderings group, it can be dropped onto a page as a top-level structural element. But critically, it can also be placed inside another Layout Container, creating a recursive composition model that is genuinely rare in out-of-the-box Sitecore experiences.
Consider some concrete scenarios where this nesting capability becomes indispensable:
Scenario A: The Marketing Landing Page. A content author building a campaign page might want a full-width hero at the top, then a three-column content row (icons + text), then a two-column row (image left, rich text right), then a full-width CTA strip. Without the Layout Container, this requires a developer to hardcode multiple distinct page template zones or create bespoke wrapper components. With it, the author drops Layout Containers like building blocks - no development ticket required.
Scenario B: The Card Grid Within a Tab. A developer has built a Tabs component. Inside each tab, a content author wants to place a 2×3 grid of Card components. Without a nestable layout primitive, the developer either has to bake the grid logic into the Tabs component (coupling concerns that should be separate) or accept that the tab body is a single linear column. With the Layout Container nested inside the tab's placeholder, the author gets the grid; the developer keeps a clean separation of concerns.
Scenario C: Asymmetric Editorial Layouts. A content team building a magazine-style article page wants a wide left column for body text and a narrow right column for a related-links sidebar, with the sidebar itself containing a small two-column author bio grid. This is a nested grid - a layout inside a layout inside a layout. Without a universal container, you either write it in code (slow, inflexible) or you don't do it at all (bad for editors). With the Layout Container, the author assembles it themselves in Pages, live, without a deployment.
This nesting behavior is not merely a developer convenience - it is a fundamental empowerment of the content author role, and it is one of the clearest indicators that whoever designed this component understood the day-to-day reality of editorial workflows.
Configuration Options - What Authors Can Control
Based on the component's architecture and the Headless SXA rendering parameters pattern, the Layout Container exposes a meaningful set of authoring controls in XM Cloud Pages:
Grid Parameters inherit from the SXA grid system, allowing authors to choose how the container spans the page grid (full width, contained, offset columns). This is the same parameter available on every SXA component, so authors already know how to use it.
Custom CSS Classes / Styles can be passed as additional rendering parameters, enabling developers to pre-define named variants (e.g., "layout--highlight-band", "layout--dark-bg") that authors can select without touching code. This is the Headless SXA variant pattern applied at the structural level.
Column Count and Layout Mode parameters map to specific CSS Grid configurations in the SCSS module, letting authors switch between common layouts (equal columns, sidebar-left, sidebar-right, masonry-ready) through a simple dropdown in Pages - no CSS knowledge required.
Spacing Controls allow authors to add or remove padding between the container and its children, supporting the common design system requirement of consistent whitespace tokens (e.g., spacing-sm, spacing-md, spacing-lg).
The beauty of the params-based approach is that developers define the vocabulary (which class names and configurations are valid) while authors make the choices within that vocabulary. It strikes the precise balance between control and guardrails that every enterprise DXP project demands.
Reusability, Extensibility, and the Development Workflow
From a developer's perspective, the Layout Container represents a philosophy shift in how Headless SXA projects should be structured. Instead of building N bespoke two-column, three-column, or asymmetric-layout components - each with its own rendering definition, datasource template, and SCSS file - you build one structural primitive and compose everything else on top of it.
This has a profound effect on the development lifecycle:
- Onboarding time drops. New developers on the project only need to learn one layout abstraction, not a proliferating zoo of structural wrapper components.
- QA scope shrinks. One well-tested Layout Container component, rather than a dozen layout variants, means fewer regression paths when the design system updates.
- Extending it is trivial. Want to add a new layout variant (say, a five-column grid for a data dashboard)? Add a CSS class to the SCSS module, add the parameter value to the rendering parameters template in Sitecore, and the new layout is immediately available to content authors. The component code itself does not change.
- Designers and developers speak the same language. When the layout vocabulary is codified in a single component's parameter schema, design token changes and grid system updates have a single, clear, authoritative integration point.
Content authors, meanwhile, gain something that is often underestimated in its value: the confidence to experiment. When a layout is a drag-and-drop combination of Layout Containers and components rather than a hardcoded template, authors can try different page structures, get feedback from stakeholders, and iterate - all without waiting for a sprint cycle.
The Big Question - Why Isn't This Already in the Base Image?
Let's step back and state what should, by now, be obvious: the Layout Container component solves a universal problem. Not a vertical-specific problem. Not a "large enterprise only" problem. Not a "nice to have for power users" problem. Every single Headless SXA project built on XM Cloud needs a way for content authors to compose multi-column, responsive page layouts without developer intervention. Every. Single. One.
Which makes the central question of this post genuinely difficult to dismiss: Why is this component not shipped as a standard part of the XM Cloud Headless SXA base image?
The Starter Kit (xmcloud-foundation-head) ships with a solid collection of baseline components - Rich Text, Image, Promo, Navigation, Container, and others. These give teams a running start with content-level components. But the Layout Container - a structural primitive that sits one level of abstraction above all of those - is absent. Teams that don't discover this Labs repository must either build their own (reinventing the wheel, probably with less polish) or ship projects where content authors are constrained to the column structures that developers hardcoded during the initial build.
Consider the cumulative cost of that gap across the Sitecore partner and customer ecosystem. Every implementation team that has ever built a bespoke "TwoColumnLayout.tsx" or "SidebarWrapper.tsx" component - which is almost certainly every implementation team - has spent time solving a problem that this component already solves cleanly and correctly. That is not just redundant effort; it is inconsistent effort, producing different quality levels, different authoring experiences, and different maintenance burdens across the ecosystem.
There is also an onboarding and adoption story to consider. XM Cloud's pitch to new customers and partners includes the power of XM Cloud Pages and the visual, drag-and-drop composability of Headless SXA. But that pitch rings hollow if the first thing an author discovers is that they cannot create a two-column layout without filing a ticket. Including the Layout Container in the base image would make the out-of-the-box authoring experience substantially more compelling - not just for power users, but for day-one evaluators.
To be clear: the Sitecore Labs team deserves real credit for building this and publishing it openly. Making it available as a discoverable Labs component is genuinely better than not having it at all, and the quality of the implementation reflects careful thinking about how it should work within the Sitecore ecosystem. The installation guide is clear, the integration path is clean, and the component follows all the right conventions.
But "discoverable if you know to look for it" is a fundamentally different value proposition than "available by default." The former relies on developers reading the right blog posts (like this one, perhaps!), attending the right community sessions, or being lucky enough to have a colleague who found it first. The latter means every XM Cloud customer gets the benefit from day one - regardless of their implementation partner's GitHub browsing habits.
If the hesitation is about keeping the base image lean and avoiding "bloat," that concern is understandable but worth challenging. The Layout Container is not an opinionated business component - it carries no brand, no domain logic, and no content model assumptions. It is as unopinionated as a <div>. It is infrastructure. And infrastructure belongs in the foundation, not in a labs addendum.
If the hesitation is about support scope - that adding more components to the base increases the surface area Sitecore must maintain - then perhaps the answer is a tiered model: a curated "recommended additions" bundle that partners and customers can opt into during project setup, with the Layout Container as its flagship entry.
Whatever the path, the status quo is leaving value on the table. Every XM Cloud project that ships without this component, or ships with a lesser hand-rolled substitute, is a reminder of a gap that Sitecore Labs has already, quietly, filled. It's time to bring it in from the cold.
Have you considered integrating the Layout Container into your SitecoreAI project? Drop a comment below or reach out on the Sitecore Community Slack - I'd love to hear how your team has extended it, what rendering parameter configurations you've found most useful, and whether you've hit any edge cases with deep nesting in XM Cloud Pages. And if you haven't explored it yet, the GitHub repository is the place to start - your content authors will thank you for it.