Balanced Layout V2 API

Create masonry-style layouts with automatic height balancing via JSON

Back to Component Examples

About Balanced Layouts

The balanced layout (masonry-style) automatically distributes items across columns by placing each item in the currently shortest column. This creates a visually harmonious layout, especially when items have varying heights. Unlike a regular grid where rows are aligned, balanced layouts minimize whitespace gaps.

Example 1: Basic Balanced Layout

A simple balanced layout with cards of varying heights. Items are automatically distributed to create visual balance.

JavaScript Code • V2 API
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "balanced-demo",
    breakpoints: { xs: 1 },  // Outer layout (single column wrapper)
    items: [{
        content: {
            type: "balanced",
            breakpoints: { xs: 1, md: 2, lg: 3 },  // Inner balanced columns
            gap: "1.5rem",
            items: [
                { html: '<div class="demo-card">...</div>' },
                { html: '<div class="demo-card">...</div>' },
                // ... more items
            ]
        }
    }]
});

Example 2: Mixed Content Cards

Balanced layout using V2 semantic card content types. Each card can contain nested content types like headings, paragraphs, and buttons.

JavaScript Code • V2 API
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "balanced-cards",
    breakpoints: { xs: 1 },  // Outer layout wrapper
    items: [{
        content: {
            type: "balanced",
            breakpoints: { xs: 1, sm: 2, lg: 3, xl: 4 },
            gap: "1rem",
            items: [
                {
                    content: {
                        type: "card",
                        title: "Quick Feature",
                        body: "A brief description.",
                        buttons: [{ text: "Learn More", variant: "primary" }]
                    }
                },
                {
                    content: {
                        type: "card",
                        title: "Extended Feature",
                        subtitle: "With more details",
                        body: "Longer description...",
                        buttons: [{ text: "Try It", variant: "success" }]
                    }
                }
                // ... more cards
            ]
        }
    }]
});

Example 3: Responsive Columns

Demonstrates responsive breakpoints: 1 column on mobile, 2 on tablets, 3 on small desktops, and 4 on large screens. Resize your browser to see the effect.

JavaScript Code • V2 API
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "balanced-responsive",
    breakpoints: { xs: 1 },  // Outer layout wrapper
    items: [{
        content: {
            type: "balanced",
            // Full responsive breakpoint control for the balanced grid
            breakpoints: {
                xs: 1,   // 0-576px: 1 column
                sm: 2,   // 577-768px: 2 columns
                md: 2,   // 769-992px: 2 columns
                lg: 3,   // 993-1200px: 3 columns
                xl: 4,   // 1201-1600px: 4 columns
                xxl: 5   // 1601px+: 5 columns
            },
            gap: "1.25rem",
            items: [
                // Your items here
            ]
        }
    }]
});

API Reference

Configuration Options

Property Type Description
type String Must be "balanced"
breakpoints Object Column counts per breakpoint: { xs: 1, sm: 2, md: 3, lg: 4, xl: 4, xxl: 5 }
slots Object Alias for breakpoints
gap String Gap between items (e.g., "1rem", "20px")
items Array Array of item configurations with content, html, or text
classes Array Additional CSS classes for the container
id String Optional ID for the container (auto-generated if not provided)
container String Optional wrapper: "default", "fluid", "full", "flex"
style Object Inline styles as key-value pairs

Item Configuration

Each item in the items array can have: