Grid Layout

⭐Star

👑Pioneer

v0.0.4+

TuiGrid is an advanced two-dimensional layout container encapsulated based on the native CSS Grid specification. It allows you to precisely control the height of each row, the width of each column, and cell merging (row-span/col-span) behaviors through simple configuration objects.

Core Concepts

Before getting started, it is important to understand the sizing unit logic of TuiGrid:

• Number: Converted to fr units (fractional/remaining space ratio). For example, size: 2 is equivalent to 2fr.
• String: Rendered directly as a CSS value. Standard CSS Grid syntax such as px, %, auto, and minmax() is supported.

Basic Usage: Fractional Ratios

The simplest usage is using numbers to define the proportions of rows and columns. In the example below, the width of the 2nd column (size: 2) is twice that of the 1st and 3rd columns, and the 4th column (size: 3) is three times that of the 1st column.

<template>
  <TuiGrid 
    :rows="2" 
    :cols="4"
    :colConfig="[
      { size: 1 },    // 1fr
      { size: 2 },    // 2fr (double width)
      { size: 1 },    // 1fr
      { size: 3 }     // 3fr (triple width)
    ]"
    :rowConfig="[
      { size: 1 },    // 1fr
      { size: 2 }     // 2fr (double height)
    ]"
  >
    <template #cell-0-0><div>1fr</div></template>
    <template #cell-0-1><div>2fr</div></template>
    <template #cell-0-2><div>1fr</div></template>
    <template #cell-0-3><div>3fr</div></template>
    <template #cell-1-0><div>Row 2</div></template>
  </TuiGrid>
</template>

Mixed Layouts

You can freely mix fixed pixels (px), percentages (%), and flexible units (fr). This is extremely useful for building classic "fixed sidebar + fluid content area" layouts.

<template>
  <TuiGrid 
    :rows="3" 
    :cols="3"
    :colConfig="[
      { size: '200px' },   // Fixed sidebar
      { size: 1 },         // Fluid center
      { size: '20%' }      // Right sidebar occupies 20% of total width
    ]"
    :rowConfig="[
      { size: '60px' },    // Fixed header
      { size: 1 },         // Content area expands to fill remaining space
      { size: '40px' }     // Fixed footer
    ]"
  >
    <template #cell-0-0><div>Header Left</div></template>
    <template #cell-0-1><div>Header Main</div></template>
    </TuiGrid>
</template>

Cell Merging

Through the cellConfig property, you can specify the number of rows (rowSpan) or columns (colSpan) that any cell should span. The configuration key is a coordinate string in the format 'rowIndex-colIndex'.

Tip

When a cell spans multiple positions, the covered cell positions still exist logically, but usually do not need to be filled with content (or can be explicitly hidden via hidden: true).

<template>
  <TuiGrid 
    :rows="4" :cols="4" :gap="20"
    :cellConfig="{
      '0-0': { colSpan: 4, className: 'header-cell' },             // Header: spans 4 columns
      '1-0': { rowSpan: 2, colSpan: 2 },                           // Main Chart: spans 2 rows and 2 columns
      '3-0': { colSpan: 4 }                                        // Footer: spans 4 columns
    }"
  >
    <template #cell-0-0>
      <div class="header">Data Dashboard Title</div>
    </template>

    <template #cell-1-0>
      <div class="big-chart">Main Chart Area</div>
    </template>

    <template #cell-1-2><div>Chart A</div></template>
    <template #cell-1-3><div>Chart B</div></template>
    
    <template #cell-3-0><div>Footer Info</div></template>
  </TuiGrid>
</template>

Advanced CSS Functions

TuiGrid fully supports advanced CSS Grid functions like minmax() and auto, enabling the creation of responsive and robust layouts.

• auto: Adjusts size automatically based on content.
• minmax(min, max): Sizes change elastically between a minimum and maximum value.

<template>
  <TuiGrid 
    :rows="1" :cols="3"
    :colConfig="[
      { size: 'auto' },                    // Width determined by content
      { size: 'minmax(200px, 1fr)' },      // Minimum 200px, fills remaining space when available
      { size: 'minmax(100px, 300px)' }     // Scales between 100px and 300px
    ]"
  >
    <template #cell-0-0>
      <div>A very long string of non-breaking text that will widen this column</div>
    </template>
    </TuiGrid>
</template>

Style Customization

CSS Variables

The Grid component exposes a set of CSS variables, allowing you to easily control the default styles of internal cells from a parent level.

.my-grid-container {
  /* Change default cell background color */
  --tui-grid-item-bg: var(--common-bg_layer);
  
  /* Change cell border */
  --tui-grid-item-bd: 1px solid rgba(255,255,255,0.1);
  
  /* Change cell padding */
  --tui-grid-item-pd: 20px;
}

Custom Class Names

Within cellConfig, you can add a className to specific cells to perform special style overrides (such as background color, alignment, etc.).

const cellConfig = {
  '0-0': { colSpan: 4, className: 'dashboard-header-style' }
}

Cell Style Classes

TuiGrid automatically attaches a set of CSS class names to every rendered cell. This allows you to target cells directly by coordinates or reuse styles by injecting custom semantic class names.

The class list for each cell consists of three parts:

1. Base Identifier: tui-grid-item The default base class name for all TuiGrid cells.
2. Coordinate Identifier: tui-cell-{row}-{col} A unique identifier automatically generated based on the cell's row and column index.
   • Indices start at 0.
   • Example: Row 1, Column 1 is .tui-cell-0-0; Row 2, Column 3 is .tui-cell-1-2.
   • Use Case: Useful for quickly overriding styles at a fixed position (like the top-left corner) via CSS without modifying JS configuration.
3. Custom Identifier: className The custom class name injected via the cellConfig configuration item.
   • Use Case: Used for semantic style management (e.g., .header-cell, .active-card).

Rendering Example

Assuming the following configuration:

const cellConfig = {
  // Add custom class name to cell at position 0-0
  '0-0': { colSpan: 4, className: 'dashboard-header' }
}

The final rendered HTML structure will look similar to:

<div class="tui-grid-item tui-cell-0-0 dashboard-header" ...>
  </div>

<div class="tui-grid-item tui-cell-0-1" ...>
  ...
</div>

Styling Tips

Using these class names, you can write styles flexibly:

/* 1. Global modification for all cells */
.tui-grid-item {
  transition: all 0.3s;
}

/* 2. Precise Target: Modify the background of row 2, column 3 */
.tui-cell-1-2 {
  background-color: #f5f5f5;
}

/* 3. Semantic Target: Modify all header cells */
.dashboard-header {
  font-weight: bold;
  border-bottom: 2px solid blue;
}

API Reference

Props

Property	Type	Default	Description
rows	Number	3	Number of grid rows.
cols	Number	3	Number of grid columns.
gap	Number/String	-	Grid spacing. Numbers are converted to px.
rowConfig	Array	[]	Row height configuration array. Format: { size: Number/String }.
colConfig	Array	[]	Column width configuration array. Format: { size: Number/String }.
cellConfig	Object	{}	Cell configuration table. Key is 'rowIndex-colIndex'.

Cell Configuration Object

The objects in cellConfig support the following properties:

Property	Type	Description
rowSpan	Number	Number of rows the cell spans.
colSpan	Number	Number of columns the cell spans.
hidden	Boolean	Whether to hide the cell (usually used for cells covered by a merge).
className	String	Custom CSS class name for the cell.

Slots

Slot names are dynamically generated in the format: cell-{rowIndex}-{colIndex}.

• Indices start at 0.
• Example: Row 1, Column 1 is cell-0-0; Row 2, Column 3 is cell-1-2.

CSS Variables

Variable Name	Default Value	Description
--tui-grid-item-bg	var(--common-bg)	Cell background color.
--tui-grid-item-bd	var(--common-bd)	Cell border style.
--tui-grid-item-pd	10px	Cell padding.
--tui-grid-w	100%	Grid container width.
--tui-grid-h	100%	Grid container height.