Grid

Grid components 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.

grid.ts

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

export default golemForm().create({
  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',
        },
      ],
    },
  ],
});

grid.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 component.

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

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.

grid.ts

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

export default golemForm().create({
  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',
        },
      ],
    },
  ],
});

grid.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.

grid.ts

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

export default golemForm().create({
  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',
        },
      ],
    },
  ],
});

grid.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.

grid.ts

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

export default golemForm().create({
  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,
        },
      ],
    },
  ],
});

grid.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
        }
      ]
    }
  ]
}

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.

grid.ts

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

export default golemForm().create({
  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,
            },
          ],
        },
      ],
    },
  ],
});

grid.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 component.

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 Component in case you want to use your CSS styles.

grid-anatomy.html

<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>