Grid

Grid widgets are Layout Fields that use CSS Grid to arrange child widgets in rows or columns. Unlike Flex, Grid leverages CSS subgrid to keep labels, inputs, and validation messages aligned across all children in a row.

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.inputs.textInput('c1', {
      label: 'Column Field 1',
      uid: 'c1',
    }),
    gui.inputs.textInput('c2', {
      label: 'Column Field 2',
      uid: 'c2',
    }),
  ], {
    direction: 'column',
    uid: 'grid_column',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_column",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "column"
      },
      "children": [
        {
          "uid": "c1",
          "kind": "input",
          "type": "textinput",
          "path": "c1",
          "label": "Column Field 1"
        },
        {
          "uid": "c2",
          "kind": "input",
          "type": "textinput",
          "path": "c2",
          "label": "Column Field 2"
        }
      ]
    }
  ]
}

Props

Use these props to customize your Grid widget.

prop	type	description
`align`	string	Main-axis distribution (`justify-content` in row, `align-content` in column). Values: `'start'`, `'end'`, `'center'`, `'space-between'`, `'space-around'`, `'space-evenly'`, `'stretch'`. Defaults to `'stretch'`
`autoFit`	boolean	When `true` (requires `direction: "row"`), columns resize automatically to fill available space. Defaults to `true`
`columnGap`	number	Space between columns in pixels. Defaults to `--gui-space-4`
`direction`	string	Grid direction: `'row'` or `'column'`. Defaults to `'row'`
`justify`	string	Cross-axis alignment (`align-items` in row, `justify-items` in column). Values: `'start'`, `'end'`, `'center'`, `'stretch'`
`rowGap`	number	Space between rows in pixels. Defaults to `--gui-space-2`

Row Layout

Set direction to "row" to place child widgets side-by-side in equal columns. On small screens (max-width: 480px), row layouts automatically stack vertically for better mobile usability.

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.inputs.textInput('r1', {
      label: 'Left Field',
      uid: 'r1',
    }),
    gui.inputs.textInput('r2', {
      label: 'Right Field',
      uid: 'r2',
    }),
  ], {
    direction: 'row',
    uid: 'grid_row',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_row",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "row"
      },
      "children": [
        {
          "uid": "r1",
          "kind": "input",
          "type": "textinput",
          "path": "r1",
          "label": "Left Field"
        },
        {
          "uid": "r2",
          "kind": "input",
          "type": "textinput",
          "path": "r2",
          "label": "Right Field"
        }
      ]
    }
  ]
}

Auto Fit Columns

By default, a direction: "row" grid divides available space into 12 equal columns. Child widgets use the size property (1–12) to span a number of those columns, giving you precise control over the layout.

Setting autoFit: true makes each child grow equally to fill the available space and wrap to the next row when the container gets too narrow — no explicit size values needed. If you do set size on a child, it will grow proportionally relative to its siblings in the same row.

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.inputs.textInput('firstName', {
      label: 'First Name',
      uid: 'af1',
    }),
    gui.inputs.textInput('lastName', {
      label: 'Last Name',
      uid: 'af2',
    }),
    gui.inputs.textInput('email', {
      label: 'Email',
      uid: 'af3',
    }),
  ], {
    direction: 'row',
    autoFit: true,
    uid: 'grid_auto_fit',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_auto_fit",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "row",
        "autoFit": true
      },
      "children": [
        {
          "uid": "af1",
          "kind": "input",
          "type": "textinput",
          "path": "firstName",
          "label": "First Name"
        },
        {
          "uid": "af2",
          "kind": "input",
          "type": "textinput",
          "path": "lastName",
          "label": "Last Name"
        },
        {
          "uid": "af3",
          "kind": "input",
          "type": "textinput",
          "path": "email",
          "label": "Email"
        }
      ]
    }
  ]
}

Child Sizes

Use the size property on child widgets to control how many columns they span. A child with size: 2 takes up twice the space of a default child.

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.inputs.textInput('s1', {
      label: 'Default Size (1)',
      uid: 's1',
    }),
    gui.inputs.textInput('s2', {
      label: 'Size 2',
      size: 2,
      uid: 's2',
    }),
  ], {
    direction: 'row',
    uid: 'grid_sizes',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_sizes",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "row"
      },
      "children": [
        {
          "uid": "s1",
          "kind": "input",
          "type": "textinput",
          "path": "s1",
          "label": "Default Size (1)"
        },
        {
          "uid": "s2",
          "kind": "input",
          "type": "textinput",
          "path": "s2",
          "label": "Size 2",
          "size": 2
        }
      ]
    }
  ]
}

Gaps

Use columnGap and rowGap (both in pixels) to control the spacing between columns and between wrapped rows. They default to --gui-space-4 and --gui-space-2 respectively.

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.inputs.textInput('g1', {
      label: 'Field 1',
      uid: 'g1',
    }),
    gui.inputs.textInput('g2', {
      label: 'Field 2',
      uid: 'g2',
    }),
    gui.inputs.textInput('g3', {
      label: 'Field 3',
      uid: 'g3',
    }),
    gui.inputs.textInput('g4', {
      label: 'Field 4',
      uid: 'g4',
    }),
    gui.inputs.textInput('g5', {
      label: 'Field 5',
      uid: 'g5',
    }),
    gui.inputs.textInput('g6', {
      label: 'Field 6',
      uid: 'g6',
    }),
  ], {
    direction: 'row',
    columnGap: 40,
    rowGap: 24,
    uid: 'grid_gaps',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_gaps",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "row",
        "columnGap": 40,
        "rowGap": 24
      },
      "children": [
        {
          "uid": "g1",
          "kind": "input",
          "type": "textinput",
          "path": "g1",
          "label": "Field 1"
        },
        {
          "uid": "g2",
          "kind": "input",
          "type": "textinput",
          "path": "g2",
          "label": "Field 2"
        },
        {
          "uid": "g3",
          "kind": "input",
          "type": "textinput",
          "path": "g3",
          "label": "Field 3"
        },
        {
          "uid": "g4",
          "kind": "input",
          "type": "textinput",
          "path": "g4",
          "label": "Field 4"
        },
        {
          "uid": "g5",
          "kind": "input",
          "type": "textinput",
          "path": "g5",
          "label": "Field 5"
        },
        {
          "uid": "g6",
          "kind": "input",
          "type": "textinput",
          "path": "g6",
          "label": "Field 6"
        }
      ]
    }
  ]
}

Alignment

Use align to distribute children along the main axis (justify-content in a row) and justify to align them on the cross axis (align-items in a row). This example spaces the columns apart with align: "space-between" and centres them with justify: "center".

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.inputs.textInput('a1', {
      label: 'First',
      uid: 'a1',
    }),
    gui.inputs.textInput('a2', {
      label: 'Second',
      uid: 'a2',
    }),
    gui.inputs.textInput('a3', {
      label: 'Third',
      uid: 'a3',
    }),
  ], {
    direction: 'row',
    autoFit: false,
    align: 'space-between',
    justify: 'center',
    uid: 'grid_alignment',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_alignment",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "row",
        "autoFit": false,
        "align": "space-between",
        "justify": "center"
      },
      "children": [
        {
          "uid": "a1",
          "kind": "input",
          "type": "textinput",
          "path": "a1",
          "label": "First"
        },
        {
          "uid": "a2",
          "kind": "input",
          "type": "textinput",
          "path": "a2",
          "label": "Second"
        },
        {
          "uid": "a3",
          "kind": "input",
          "type": "textinput",
          "path": "a3",
          "label": "Third"
        }
      ]
    }
  ]
}

Nested Grids

Combine a column Grid with row Grid children to build complex form layouts. Each row aligns its labels, inputs, and validation messages independently through subgrid.

import { gui } from '@golemui/gui-shared';

export default [
  gui.layouts.grid([
    gui.layouts.grid([
      gui.inputs.textInput('n1', {
        label: 'First Name',
        uid: 'n1',
      }),
      gui.inputs.textInput('n2', {
        label: 'Last Name',
        uid: 'n2',
      }),
    ], {
      direction: 'row',
      uid: 'grid_row_1',
    }),
    gui.layouts.grid([
      gui.inputs.textInput('n3', {
        label: 'Email',
        uid: 'n3',
      }),
      gui.inputs.textInput('n4', {
        label: 'Phone',
        size: 2,
        uid: 'n4',
      }),
    ], {
      direction: 'row',
      uid: 'grid_row_2',
    }),
  ], {
    direction: 'column',
    uid: 'grid_outer',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "grid_outer",
      "kind": "layout",
      "type": "grid",
      "props": {
        "direction": "column"
      },
      "children": [
        {
          "uid": "grid_row_1",
          "kind": "layout",
          "type": "grid",
          "props": {
            "direction": "row"
          },
          "children": [
            {
              "uid": "n1",
              "kind": "input",
              "type": "textinput",
              "path": "n1",
              "label": "First Name"
            },
            {
              "uid": "n2",
              "kind": "input",
              "type": "textinput",
              "path": "n2",
              "label": "Last Name"
            }
          ]
        },
        {
          "uid": "grid_row_2",
          "kind": "layout",
          "type": "grid",
          "props": {
            "direction": "row"
          },
          "children": [
            {
              "uid": "n3",
              "kind": "input",
              "type": "textinput",
              "path": "n3",
              "label": "Email"
            },
            {
              "uid": "n4",
              "kind": "input",
              "type": "textinput",
              "path": "n4",
              "label": "Phone",
              "size": 2
            }
          ]
        }
      ]
    }
  ]
}

Styling

Grid layouts can be styled as explained in the Styling Guide.

CSS Variables

Following you will find a list with the CSS Variables used to control spacing within the Grid widget.

CSS Variable	Description
`--gui-space-4`	Default column gap between widgets
`--gui-space-2`	Default row gap between widgets
`--gui-space-1`	Gap inside each grid cell (subgrid)

Anatomy

This is the anatomy of the Grid Widget in case you want to use your CSS styles.

<div class="gui-grid">
  <div class="gui-grid__widget gui-grid__widget--row" id="grid_uid">

    <div class="gui-grid__cell" style="grid-column: span 1">
      <gui-widget>
        <!-- Child 1 content -->
      </gui-widget>
    </div>

    <div class="gui-grid__cell" style="grid-column: span 2">
      <gui-widget>
        <!-- Child 2 content (size: 2) -->
      </gui-widget>
    </div>

  </div>
</div>