Article Type: How-To / Tutorial
Audience: Application Designers, Dashboard Builders, Developers
Module: Screen Designer
Applies to Versions: All current versions

1. Overview

The Grid Container layout provides a powerful way to create structured, responsive dashboard layouts in Fuuz. Unlike the default Flex layout which arranges items in rows or columns, the Grid layout allows you to define a precise two-dimensional matrix of cells where components can be positioned and sized exactly where you need them.

This article explains how to:

• Configure a Container to use Grid layout
• Define grid dimensions (rows and columns)
• Place components within the grid
• Use Grid Cells for components that span multiple rows or columns
• Create nested grids for complex layouts
• Make grid properties dynamic using JSONata transforms

2. Key Concepts

Grid vs. Flex Layout

Grid Terminology

• Grid Container: A Container component with layout: "grid" that defines the overall grid structure
• Columns: The number of vertical divisions in the grid
• Rows: The number of horizontal divisions in the grid
• Grid Cell: A special component that can span multiple columns and/or rows
• Column Span (colSpan): How many columns a Grid Cell occupies horizontally
• Row Span (rowSpan): How many rows a Grid Cell occupies vertically
• Justify Items: How items are aligned horizontally within their cells (start, center, end, stretch)

3. Creating a Grid Container

Step 1: Add a Container Component

1. Open the Screen Designer
2. Drag a Container component from the component palette onto your screen
3. Select the Container to view its properties in the right panel

Step 2: Set Layout to Grid

1. In the Container properties panel, locate the Layout property
2. Change the value from "flex" to "grid"
3. Additional grid-specific properties will appear

Step 3: Configure Grid Dimensions

1. Set the Columns property to define how many columns the grid should have (e.g., 5)
2. Set the Rows property to define how many rows the grid should have (e.g., 5)
3. Optionally, set Justify Items to control horizontal alignment within cells

Grid Container Properties Reference

Example Configuration (JSON)

{
  "type": "Container",
  "props": {
    "layout": "grid",
    "columns": 5,
    "rows": 5,
    "justifyItems": "center",
    "width": "100%",
    "height": "auto",
    "margin": 1,
    "background": "default"
  }
}

4. Adding Items to the Grid

Basic Item Placement

Items placed inside a Grid Container automatically flow into the grid cells from left to right, top to bottom. Each child component occupies one cell by default.

1. Select your Grid Container in the component tree
2. Drag components (buttons, text, charts, etc.) into the container
3. Components will fill cells in order: Cell 1, Cell 2, Cell 3, etc.

For a 5x5 grid (25 cells), if you add 25 buttons, they will fill the grid completely, one per cell.

Understanding Cell Order

Grid cells are filled in reading order (left-to-right, top-to-bottom):

5x5 Grid Cell Order:

  Col1  Col2  Col3  Col4  Col5
  ----  ----  ----  ----  ----
   1     2     3     4     5    ← Row 1
   6     7     8     9    10    ← Row 2
  11    12    13    14    15    ← Row 3
  16    17    18    19    20    ← Row 4
  21    22    23    24    25    ← Row 5

The order of child components in the component tree determines which cell they occupy.

5. Using Grid Cells for Spanning

When you need a component to occupy more than one cell (span multiple columns or rows), use the Grid Cell component.

Adding a Grid Cell

1. With your Grid Container selected, drag a Grid Cell component into it
2. The Grid Cell will occupy its position in the cell order
3. Configure the spanning properties on the Grid Cell
4. Place your content inside the Grid Cell

Grid Cell Properties Reference

Example: 2x2 Spanning Cell

A Grid Cell with colSpan: 2 and rowSpan: 2 placed as the first child would occupy cells 1, 2, 6, and 7:

5x5 Grid with 2x2 Spanning Cell:

  Col1  Col2  Col3  Col4  Col5
  ----  ----  ----  ----  ----
  [  SPAN  ]   3     4     5    ← Row 1
  [  CELL  ]   8     9    10    ← Row 2
  11    12    13    14    15    ← Row 3
  16    17    18    19    20    ← Row 4
  21    22    23    24    25    ← Row 5

Grid Cell JSON Example

{
  "type": "GridCell",
  "props": {
    "colSpan": 2,
    "rowSpan": 2
  },
  "children": [
    // Your content goes here (containers, charts, widgets, etc.)
  ]
}

6. Nested Grids

For complex layouts, you can nest grids inside each other. Place a Container with layout: "grid" inside a Grid Cell to create a sub-grid.

Example: Dashboard with Header and Sub-Grid

Outer Grid (3 columns x 3 rows):

  [   Header spanning 3 columns   ]  ← Row 1 (GridCell colSpan: 3)
  [ Nav ]  [ Main Content Grid  ]   ← Row 2 (GridCell + nested 2x2 grid)
  [     Footer spanning 3 cols    ]  ← Row 3 (GridCell colSpan: 3)

Main Content Nested Grid (2x2):
  [ Chart 1 ]  [ Chart 2 ]
  [ Chart 3 ]  [ Chart 4 ]

Implementation Steps

1. Create the outer Grid Container (e.g., 3x3)
2. Add Grid Cells for header and footer with colSpan: 3
3. Add a Grid Cell for the main content area
4. Inside the main content Grid Cell, add a Container with layout: "grid"
5. Configure the nested grid's columns and rows (e.g., 2x2)
6. Add chart/widget components to the nested grid

7. Dynamic Grid Properties

Grid properties can be made dynamic using JSONata transforms. This allows the grid structure to change based on user input, screen size, data conditions, or other factors.

Dynamic Columns and Rows

You can bind the columns and rows properties to form data, context, or calculations:

// Dynamic columns from a form field
{
  "columns": {
    "__transform": "$components.Form1.data.columns",
    "__fallbackValue": 5
  }
}

// Dynamic rows based on data count
{
  "rows": {
    "__transform": "$ceil($count($components.Table1.data) / 5)",
    "__fallbackValue": 3
  }
}

Dynamic Cell Spanning

Grid Cell span properties can also be dynamic:

// Dynamic column span from form
{
  "colSpan": {
    "__transform": "$components.Form1.data.colSpan",
    "__fallbackValue": 2
  },
  "rowSpan": {
    "__transform": "$components.Form1.data.rowSpan",
    "__fallbackValue": 2
  }
}

8. Common Dashboard Patterns

Pattern 1: KPI Dashboard (4x2)

A simple grid with 8 KPI tiles arranged in 2 rows:

Grid: 4 columns x 2 rows

  [ OEE ]  [ Uptime ]  [ Output ]  [ Quality ]   ← Row 1
  [ WIP ]  [ Backlog ] [ Scrap  ]  [ Downtime ]  ← Row 2

Pattern 2: Main + Detail Layout (3x2)

A large main chart with smaller detail widgets:

Grid: 3 columns x 2 rows

  [   Main Chart (2x2 span)   ]  [ Detail 1 ]   ← Row 1
  [                           ]  [ Detail 2 ]   ← Row 2

GridCell 1: colSpan=2, rowSpan=2 (Main Chart)
Cell 3: Detail widget 1
Cell 6: Detail widget 2

Pattern 3: Workcenter Status Board (5x3)

A production floor status display with one tile per workcenter:

Grid: 5 columns x 3 rows

  [ WC-01 ] [ WC-02 ] [ WC-03 ] [ WC-04 ] [ WC-05 ]  ← Line 1
  [ WC-06 ] [ WC-07 ] [ WC-08 ] [ WC-09 ] [ WC-10 ]  ← Line 2
  [ WC-11 ] [ WC-12 ] [ WC-13 ] [ WC-14 ] [ WC-15 ]  ← Line 3

Pattern 4: Calendar Week View (7x5)

A weekly calendar layout with time slots:

Grid: 7 columns x 5 rows

  [ Sun ] [ Mon ] [ Tue ] [ Wed ] [ Thu ] [ Fri ] [ Sat ]  ← Day Headers
  [ AM  ] [ AM  ] [ AM  ] [ AM  ] [ AM  ] [ AM  ] [ AM  ]  ← Morning slots
  [ Mid ] [ Mid ] [ Mid ] [ Mid ] [ Mid ] [ Mid ] [ Mid ]  ← Midday slots
  [ PM  ] [ PM  ] [ PM  ] [ PM  ] [ PM  ] [ PM  ] [ PM  ]  ← Afternoon slots
  [ Eve ] [ Eve ] [ Eve ] [ Eve ] [ Eve ] [ Eve ] [ Eve ]  ← Evening slots

9. Demo Screen Import

The Grid Container Demo provides an interactive example you can import and experiment with.

Demo Contents

• Control Panel: Form with 4 number inputs (Columns, Rows, Column Span, Row Span)
• Grid Container: 5x5 grid with 22 child elements
• Grid Cell: Dynamically spanning cell (default 2x2) with nested content
• Numbered Buttons: 21 action buttons filling remaining cells
• Nested Grid: 2x2 grid inside the spanning Grid Cell

Import Steps

1. Obtain the Grid_Container_Demo_0_0_1.json file
2. Navigate to Screen Designer in your Fuuz application
3. Create a new screen or open an existing one
4. Use the Import function to load the JSON file
5. The demo screen will be added with all components configured

Using the Demo

1. Preview or publish the screen
2. Adjust the Columns value to see the grid reflow horizontally
3. Adjust the Rows value to see the grid change vertically
4. Modify Column Span to see the highlighted cell expand/contract horizontally
5. Modify Row Span to see the highlighted cell expand/contract vertically
6. Click numbered buttons to see their position in the grid

10. Best Practices

• Plan your grid dimensions: Sketch your layout first to determine optimal column and row counts
• Use Grid Cells sparingly: Only use Grid Cell components when you need spanning; regular components work fine for single-cell content
• Set fallback values: When using dynamic properties, always provide __fallbackValue for graceful degradation
• Consider responsive design: Use dynamic columns based on screen width for responsive dashboards
• Test spanning carefully: Ensure spanning cells don't exceed grid boundaries or overlap unintentionally
• Use consistent sizing: Set uniform width/height on grid items for a clean appearance
• Leverage nested grids: For complex layouts, nest grids rather than trying to achieve everything in one grid

11. Troubleshooting

12. Resources

• Fuuz Industrial Operations Platform — Main product site
• Screen Designer Guide — Complete Screen Designer documentation
• Container Component Reference — All Container properties and layouts
• JSONata Transform Reference — Dynamic property binding with JSONata
• Dashboard Design Best Practices — Creating effective operational dashboards

13. Revision History