Named Grid Areas

What are Named Grid Areas?

Named Grid Areas let you create complex, asymmetric layouts by defining semantic regions like "header", "sidebar", "content", and "footer". Instead of thinking in columns and rows, you design with meaningful layout areas that automatically adjust to different screen sizes.

💡 Two Ways to Use Grid Areas:

Predefined Patterns - Use data attributes for common layouts (holy-grail, sidebar, app-shell, etc.)
Custom JSON Layouts - Define completely custom layouts via the JSON Layout API

Choose Your Approach

Predefined Patterns

Best for: Common layout patterns, quick setup

6 built-in patterns
Data attribute API
Responsive breakpoints
Zero JavaScript
Copy-paste ready

Custom JSON Layouts

Best for: Unique designs, dynamic content

Unlimited flexibility
Define any layout
Custom columns/rows
Programmatic generation
Database-driven layouts

Approach 1: Predefined Patterns

Use data-layout-pattern attributes for instant layouts. All patterns support responsive breakpoints.

Available Patterns

stacked

All items stack vertically. Perfect for mobile-first designs.

holy-grail

Classic header + 3-column + footer layout. Great for dashboards.

sidebar-left

Left navigation with main content area. Common for docs sites.

sidebar-right

Main content with right sidebar. Good for blogs with widgets.

app-shell

Top navbar + left sidebar + main. Modern app layout.

dashboard

Header with 4-zone content grid. Analytics dashboards.

Example: Holy Grail Layout

HTML

<div class="slot-layout"
     data-layout-pattern-xs="stacked"
     data-layout-pattern-md="holy-grail">
    <div class="slot-item" data-area="header">Header</div>
    <div class="slot-item" data-area="sidebar">Sidebar</div>
    <div class="slot-item" data-area="content">Main Content</div>
    <div class="slot-item" data-area="aside">Aside</div>
    <div class="slot-item" data-area="footer">Footer</div>
</div>

Header

Nav

Main Content

Aside

Footer

⚡ Resize Your Browser!
The layout automatically switches from stacked (mobile) to holy-grail (tablet+) at 769px width.

Approach 2: Custom JSON Layouts

For completely custom layouts, use the JSON Layout Engine V2. Define your own grid areas, columns, and rows for each breakpoint.

Basic Custom Layout

JavaScript

RSL.JSONLayout.renderLayout('#my-container', {
    version: 2,
    layoutId: "custom-app",
    gridAreas: {
        xs: {
            areas: [
                ["header"],
                ["nav"],
                ["main"],
                ["footer"]
            ],
            columns: "1fr",
            rows: "auto auto 1fr auto"
        },
        md: {
            areas: [
                ["header", "header"],
                ["nav", "main"],
                ["footer", "footer"]
            ],
            columns: "200px 1fr",
            rows: "auto 1fr auto"
        }
    },
    gap: "1rem",
    items: [
        {
            area: "header",
            content: { type: "heading", level: 1, text: "My App" }
        },
        {
            area: "nav",
            content: { type: "html", value: "<nav>Navigation</nav>" }
        },
        {
            area: "main",
            content: { type: "html", value: "<main>Content</main>" }
        },
        {
            area: "footer",
            content: { type: "text", value: "© 2025" }
        }
    ]
});

Advanced Example: Magazine Layout

JavaScript

RSL.JSONLayout.renderLayout('#magazine', {
    version: 2,
    layoutId: "magazine-layout",
    gridAreas: {
        xs: {
            areas: [
                ["hero"],
                ["featured"],
                ["article1"],
                ["article2"],
                ["sidebar"]
            ],
            columns: "1fr",
            rows: "auto"
        },
        lg: {
            areas: [
                ["hero", "hero", "hero", "featured"],
                ["article1", "article1", "article2", "sidebar"],
                ["article1", "article1", "article2", "sidebar"]
            ],
            columns: "1fr 1fr 1fr 300px",
            rows: "400px auto auto"
        }
    },
    gap: "1.5rem",
    items: [
        {
            area: "hero",
            content: {
                type: "card",
                image: "hero.jpg",
                title: "Breaking News",
                text: "Lorem ipsum dolor sit amet..."
            }
        },
        {
            area: "featured",
            content: { type: "card", title: "Featured Story" }
        },
        {
            area: "article1",
            content: { type: "card", title: "In-Depth Article" }
        },
        {
            area: "article2",
            content: { type: "card", title: "Quick Read" }
        },
        {
            area: "sidebar",
            content: { type: "html", value: "<aside>Sidebar</aside>" }
        }
    ]
});

JSON Configuration Reference

gridAreas Object

Structure

gridAreas: {
    [breakpoint]: {
        areas: [
            ["area1", "area2", "area3"],  // First row
            ["area1", "area4", "area4"]   // Second row
        ],
        columns: "200px 1fr 1fr",  // Optional, default: "1fr"
        rows: "auto 1fr"            // Optional, default: "auto"
    }
}

Property	Type	Required	Description
`areas`	Array	Yes	2D array defining grid area names. Each sub-array is a row.
`columns`	String	No	CSS grid-template-columns value (e.g., "200px 1fr 1fr")
`rows`	String	No	CSS grid-template-rows value (e.g., "auto 1fr auto")

Breakpoints

Breakpoint	Min Width	Typical Use
`xs`	0px	Mobile phones (portrait)
`sm`	577px	Mobile phones (landscape)
`md`	769px	Tablets
`lg`	993px	Desktops
`xl`	1201px	Large desktops
`xxl`	1601px	Extra large screens

Tips & Best Practices

Design Tips

Start with a mobile-first approach - define xs breakpoint first
Use semantic area names (header, nav, main) instead of generic ones (box1, box2)
Test your layout at each breakpoint to ensure smooth transitions
Combine with gap property for consistent spacing

Common Pitfalls

All rows must have the same number of columns in the areas array
Area names must be valid CSS identifiers (no spaces or special characters)
Items without an area property won't be placed in named areas
Overlapping areas in the grid require careful column/row sizing

Advanced Grid Placement

For maximum control, RSL provides data attributes to explicitly position individual items using grid-row and grid-column values. This is an escape hatch for complex layouts that need precise grid positioning.

Data Attributes

Use these attributes on any .slot-item or .nested-slot-item:

data-col-start - Grid column start line
data-col-end - Grid column end line
data-row-start - Grid row start line
data-row-end - Grid row end line

HTML Example

<div class="slot-layout" data-cols-md="4" data-cols-lg="6">
    <!-- Span 2 columns -->
    <div class="slot-item" data-col-start="1" data-col-end="3">
        Wide Item
    </div>

    <!-- Span 2 rows -->
    <div class="slot-item" data-row-start="1" data-row-end="3">
        Tall Item
    </div>

    <!-- Position in specific area -->
    <div class="slot-item" data-col-start="4" data-col-end="7" data-row-start="2">
        Positioned Item
    </div>

    <!-- Regular items fill remaining space -->
    <div class="slot-item">Item 1</div>
    <div class="slot-item">Item 2</div>
    <div class="slot-item">Item 3</div>
</div>

JSON API Example

You can also use the grid property in JSON Layout Engine V2:

RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "advanced-grid",
    breakpoints: { xs: 2, md: 4, lg: 6 },
    items: [
        {
            content: { type: "text", value: "Wide Item" },
            grid: {
                columnStart: 1,
                columnEnd: 3  // Spans 2 columns
            }
        },
        {
            content: { type: "text", value: "Tall Item" },
            grid: {
                rowStart: 1,
                rowEnd: 3  // Spans 2 rows
            }
        },
        {
            content: { type: "text", value: "Positioned Item" },
            grid: {
                columnStart: 4,
                columnEnd: 7,
                rowStart: 2
            }
        }
    ]
});

How It Works

These data attributes are automatically converted to CSS variables (--column-start, --column-end, --row-start, --row-end) which are already supported in RSL's grid system. This provides opt-in control without breaking existing layouts.

Browser Support

Named Grid Areas use CSS Grid's grid-template-areas feature, which is supported in all modern browsers:

Chrome 57+ (March 2017)
Firefox 52+ (March 2017)
Safari 10.1+ (March 2017)
Edge 16+ (October 2017)

For older browsers, the layout will degrade gracefully to a single-column stack.