Tesserae - Grid

Grid

Description

The Grid component provides a flexible layout container that arranges its child components into a grid structure. It is used primarily for collections where items need to be aligned in rows and columns. You can define custom column and row sizes and adjust layout properties like gaps, alignment, and overflow.

Usage

Instantiate a Grid using the helper method from Tesserae.UI and specify the column sizes. Items are added using the Add method, and you can customize grid behavior using chaining methods.

grid-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new GridExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class GridExample : IComponent
    {
        public HTMLElement Render()
        {
            // Create a grid with three columns: two flexible and one fixed at 200px
            var grid = Grid(columns: new[] { 1.fr(), 1.fr(), 200.px() })
                .Gap(6.px())                     // Set gap between grid items to 6px
                .JustifyContent(ItemJustify.Start);

            // Add a button spanning 2 grid rows
            grid.Add(Button().SetText("this").WS().Primary().GridColumnStretch().GridRow(1, 2));

            // Add multiple buttons to grid
            for (int i = 1; i <= 12; i++)
            {
                grid.Add(Button().SetText($"Button {i}"));
            }

            return grid.Render();
        }
    }
}

Public Properties

Background
- Get or set the background CSS property value.
Margin
- Get or set the margin CSS property value.
Padding
- Get or set the padding CSS property value.
StylingContainer
- Gets the underlying HTMLElement used for styling.
PropagateToStackItemParent
- Indicates if style changes should propagate to the parent in stack items (read-only via chaining methods).

API reference

class

Grid

public class Grid : IContainer<Grid, IComponent>, IHasBackgroundColor, IHasMarginPadding, ISpecialCaseStyling

A CSS-Grid container with explicit row and column tracks, gap and alignment, for two-dimensional layouts.

Constructors

Constructor

Grid

public Grid(params UnitSize[] columns)

Initializes a new instance of this class.

Constructor

Grid

public Grid(UnitSize[] columns, UnitSize[] rows)

Initializes a new instance of this class.

Properties

Property

Grid.Background

public string Background { get ; set ; }

Gets or sets the CSS background of the component.

Property

Grid.Margin

public string Margin { get ; set ; }

Gets or sets the CSS margin of the component.

Property

Grid.Padding

public string Padding { get ; set ; }

Gets or sets the CSS padding of the component.

Property

Grid.StylingContainer

public HTMLElement StylingContainer

Gets or sets the styling container.

Property

Grid.PropagateToStackItemParent

public bool PropagateToStackItemParent { get; private set; }

Gets or sets the propagate to stack item parent.

Methods

Method

Grid.Columns

public Grid Columns(params UnitSize[] columns)

Defines the columns of the grid (track sizes).

Method

Grid.Rows

public Grid Rows(UnitSize[] rows)

Defines the rows of the grid (track sizes).

Method

Grid.Add

public void Add(IComponent component)

Adds the given item to the component.

Method

Grid.SetGridColumn

public static void SetGridColumn(IComponent component, int start, int end)

Needs to be called before the component is added to the Grid.

Method

Grid.SetGridRow

public static void SetGridRow(IComponent component, int start, int end)

Needs to be called before the component is added to the Grid.

Method

Grid.AlignItems

public Grid AlignItems(ItemAlign align)

Sets the align-items css property for this stack

Parameters

align

Method

Grid.AlignContent

public Grid AlignContent(ItemAlign align)

Sets the align-items css property for this stack

Parameters

align

Method

Grid.JustifyContent

public Grid JustifyContent(ItemJustify justify)

Sets the justify-content css property for this stack

Parameters

justify

Method

Grid.JustifyItems

public Grid JustifyItems(ItemJustify justify)

Sets the justify-content css property for this stack

Parameters

justify

Method

Grid.Relative

public Grid Relative()

Make this grid relative (i.e. position:relative)

Method

Grid.AlignItemsCenter

public Grid AlignItemsCenter()

Sets the align-items css property for this grid to 'center'

Parameters

align

Method

Grid.OverflowHidden

public Grid OverflowHidden()

Hides any content that overflows the component's bounds.

Method

Grid.Gap

public Grid Gap(UnitSize gapSize)

Sets the gap between rows and columns of the grid.

Method

Grid.RowGap

public Grid RowGap(UnitSize gapSize)

Sets the gap between rows of the grid.

Method

Grid.ColumnGap

public Grid ColumnGap(UnitSize gapSize)

Sets the gap between columns of the grid.

Method

Grid.AutoRows

public Grid AutoRows(UnitSize autoRowValue)

Sets the auto-generated row size of the grid.

Method

Grid.AutoColumn

public Grid AutoColumn(UnitSize autoColumnValue)

Sets the auto-generated column size of the grid.

Method

Grid.FlowColumn

public Grid FlowColumn()

Switches the grid to column flow.

Method

Grid.Clear

public virtual void Clear()

Clears the component's current state.

Method

Grid.RemovePropagation

public Grid RemovePropagation()

Removes the given propagation from the component.

Method

Grid.NoDefaultMargin

public Grid NoDefaultMargin()

Removes / disables the default margin on the component.

Method

Grid.Replace

public void Replace(IComponent newComponent, IComponent oldComponent)

Replaces an existing item with a new one.

Method

Grid.Remove

public void Remove(IComponent component)

Removes the given item from the component.

Method

Grid.Render

public virtual HTMLElement Render()

Renders the component's root HTML element.

Samples

Basic Grid Sample

This sample demonstrates creating a simple grid with three columns, setting a gap between items, and adding multiple buttons.

grid-2-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new BasicGridSample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class BasicGridSample : IComponent
    {
        public HTMLElement Render()
        {
            // Create a grid with two flexible columns and one 200px fixed column.
            var grid = Grid(columns: new[] { 1.fr(), 1.fr(), 200.px() })
                .Gap(6.px())
                .JustifyContent(ItemJustify.Start);

            // Add a button that spans from column 1 to 2 rows.
            grid.Add(Button().SetText("this").WS().Primary().GridColumnStretch().GridRow(1, 2));

            // Add twelve buttons to the grid.
            for (int i = 1; i <= 12; i++)
            {
                grid.Add(Button().SetText($"Button {i}"));
            }

            // Return the rendered grid element.
            return grid.Render();
        }
    }
}

Auto-Sizing Responsive Grid

This sample uses CSS Grid's auto-fit plus minmax so the number of columns adapts to the available width — narrow viewports collapse to a single column, wide viewports show several.

grid-3-sample.js

using System.Linq;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var grid = Grid(new UnitSize("repeat(auto-fit, minmax(min(200px, 100%), 1fr))"))
                .Gap(8.px());

            Enumerable.Range(1, 12).ForEach(n =>
                grid.Add(Card(TextBlock($"Responsive #{n}").TextCenter().Padding(16.px()))));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(grid);
        }
    }
}

Row Gaps, Column Gaps and Alignment

RowGap and ColumnGap set the spacing in each direction independently. AlignItems and JustifyItems control how cells with extra space lay their content out.

grid-4-sample.js

using System.Linq;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var grid = Grid(columns: new[] { 1.fr(), 1.fr(), 1.fr() })
                .RowGap(4.px())
                .ColumnGap(24.px())
                .AlignItems(ItemAlign.Center)
                .JustifyItems(ItemJustify.Center);

            Enumerable.Range(1, 9).ForEach(n =>
                grid.Add(Card(TextBlock($"Cell {n}")).Padding(12.px()).MinWidth(80.px())));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(grid);
        }
    }
}

Spans and Manual Cell Placement

Components can occupy multiple rows or columns by using GridRow / GridColumn. This sample creates a 4-column layout where the first card is stretched across two rows and the second across two columns.

grid-5-sample.js

using System.Linq;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var grid = Grid(columns: new[] { 1.fr(), 1.fr(), 1.fr(), 1.fr() })
                .Gap(8.px());

            grid.Add(Card(TextBlock("Tall (rows 1–3)").TextCenter()).WS().HS().Padding(16.px())
                .GridColumn(1, 2).GridRow(1, 3));
            grid.Add(Card(TextBlock("Wide (cols 2–4)").TextCenter()).WS().Padding(16.px())
                .GridColumn(2, 4));

            Enumerable.Range(1, 6).ForEach(n =>
                grid.Add(Card(TextBlock($"Item {n}").TextCenter()).Padding(12.px())));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(grid);
        }
    }
}

Grid

Description

Usage

Public Properties

API reference

Constructors

Grid

Grid

Properties

Grid.Background

Grid.Margin

Grid.Padding

Grid.StylingContainer

Grid.PropagateToStackItemParent

Methods

Grid.Columns

Grid.Rows

Grid.Add

Grid.SetGridColumn

Grid.SetGridRow

Grid.AlignItems

Parameters

Grid.AlignContent

Parameters

Grid.JustifyContent

Parameters

Grid.JustifyItems

Parameters

Grid.Relative

Grid.AlignItemsCenter

Parameters

Grid.OverflowHidden

Grid.Gap

Grid.RowGap

Grid.ColumnGap

Grid.AutoRows

Grid.AutoColumn

Grid.FlowColumn

Grid.Clear

Grid.RemovePropagation

Grid.NoDefaultMargin

Grid.Replace

Grid.Remove

Grid.Render

Samples

Basic Grid Sample

Auto-Sizing Responsive Grid

Row Gaps, Column Gaps and Alignment

Spans and Manual Cell Placement

See Also

Referenced by