Grid Component

Grid divides a page into stable, reusable, responsive regions. It is useful for dashboards, detail pages, main-content-and-sidebar layouts, and equal-width card groups. Each region can contain a Form, Common Panel, ProTable, DataList, or another content component.

After reading this guide, you will be able to:

• Understand the Grid, Grid Row, and Grid Column hierarchy
• Build equal, primary-secondary, and full-width layouts with a 24-column grid
• Configure column gaps, wrap gaps, horizontal distribution, and vertical alignment
• Set a minimum column height without preventing content from growing
• Combine Grid with Forms, Panels, and data components
• Diagnose wrapping, unexpected widths, and preview/runtime differences

1. Example: Campaign operations dashboard

The Grid page in Spark Sample demonstrates three common arrangements:

Row	Column spans	Purpose
Equal Thirds	8 + 8 + 8	Three equal KPI cards
Main and Sidebar	16 + 8	Campaign details with a release checklist
Equal Halves	12 + 12	Schedule and audience regions

Screen
└── Grid: Campaign Dashboard Grid
    ├── Row: Equal Thirds
    │   ├── Column 8/24 → Audience Reach
    │   ├── Column 8/24 → Conversion
    │   └── Column 8/24 → Budget
    ├── Row: Main and Sidebar
    │   ├── Column 16/24 → Campaign Details
    │   └── Column 8/24  → Release Checklist
    └── Row: Equal Halves
        ├── Column 12/24 → Schedule
        └── Column 12/24 → Audience

The sample focuses on layout and uses initial field values, so it does not require a backend Sample API. Replace a Form with a Data Form, or add DataList or ProTable, when the regions need live business data.

2. The three-level structure

Grid is not a single container that receives content directly:

1. Grid controls horizontal distribution and vertical alignment for its rows.
2. Grid Row represents one row and controls column and wrap gaps.
3. Grid Column occupies part of the 24-column system and contains business components.

Use this order:

Grid → Grid Row → Grid Column → Common Panel / Form / data component

3. Add a Grid

1. Open the page in Page Designer and select Screen.
2. Add Grid in the Screen's Grid child area.
3. Select Grid and add a Grid Row under Rows.
4. Select the row and add one or more Grid Columns under Columns.
5. Set Span Columns on every column.
6. Add a Common Panel, Form, ProTable, or another component under the column's Panels area.
7. Save the page and check both the design canvas and runtime.

A new Grid Column defaults to 24/24, so it is immediately visible as a full-width region.

4. Use the 24-column system

Each row has 24 logical columns. Span Columns accepts 1 through 24.

Desired layout	Span Columns
Full-width region	24
Two equal regions	12 + 12
Three equal regions	8 + 8 + 8
Four equal regions	6 + 6 + 6 + 6
Main content and sidebar	16 + 8 or 18 + 6
Sidebar and main content	6 + 18 or 8 + 16

The spans in a row should usually add up to 24. A smaller total leaves free space, positioned by Horizontal Alignment. A total greater than 24 wraps later columns onto the next line.

Column Gap is visual spacing and does not have to be subtracted from 24. 8 + 8 + 8 with a 16px gap still fills one row.

5. Configure row gaps

Select a Grid Row to configure:

Property	Range	Meaning
Column Gap	0-64	Horizontal space between neighboring columns, in pixels
Row Gap	0-64	Vertical space between wrapped lines, in pixels

Start with 12-20 for a typical business page. Separate Grid Rows already use the design system's standard spacing.

6. Configure alignment

Select the outer Grid.

Horizontal Alignment

Value	Result
start	Pack columns at the start; the usual choice
end	Pack columns at the end
center	Center the group
space-between	Place free space between columns
space-around	Distribute space around each column

When spans add up to 24, there is no free horizontal space and these values may look identical. Use 8 + 8 temporarily to compare them.

Vertical Alignment

Value	Result
top	Align column tops; best for most cards
middle	Center columns vertically in the row
bottom	Align column bottoms

The difference is visible only when columns in the same row have different heights.

7. Set a minimum column height

Minimum Column Height accepts 0 through 1200 pixels:

• 0 lets the height follow the content and is the safest default.
• A positive value reserves at least that height. Taller content still expands the column and is not clipped.

Give columns in the same row the same minimum height when their cards should appear balanced. This property is not a maximum height.

8. Organize content inside columns

Grid controls page regions; child components own the business content.

• Common Panel + Form creates a titled detail or KPI card.
• Form creates an input region without an additional card title.
• ProTable / DataList works well in main areas or beside a filter/sidebar region.
• Tree normally belongs in Screen's dedicated Navigation Tree area. Put it in a Grid Column only when it is ordinary page content rather than navigation.

Grid does not replace a Form's Controls Per Row or Form Grid Split. Grid determines the region width; Form calculates its own columns and label split inside that region.

9. Recreate the sample

1. Add one Grid with Horizontal Alignment start and Vertical Alignment top.
2. Add a row with Column Gap and Row Gap set to 16.
3. Add three columns with spans 8, 8, and 8; set each minimum height to 156.
4. Put a Common Panel and a one-column read-only Form in each KPI column.
5. Add a second row with spans 16 + 8 and minimum height 228.
6. Put a two-column Form in the main region and a one-column checklist Form in the sidebar.
7. Add a third row with spans 12 + 12 and minimum height 176.
8. Save, narrow the browser window, and confirm that columns stack in configuration order.

10. Responsive behavior

At desktop widths, Grid follows the configured 24-column spans. On phones and narrow screens, columns stack as one readable column instead of squeezing forms and cards.

Stacking does not change the Page JSON or erase Span Columns. The original arrangement returns when the viewport becomes wider. Put the most important column first because mobile follows the configured order.

11. Backend and interactions

Grid is a layout-only component and sends no request itself, so a normal Grid sample requires no Java backend code. A backend is needed only when a child data component or Interaction needs business data:

• Data Form, DataList, and ProTable use their own Data Source.
• Buttons, fields, cards, and other child components own their own Interaction actions.
• Page requests automatically carry environment and render-mode context; see Page request context and backend debugging.

Do not attach a request to Grid Row or Grid Column as a substitute for the component that performs the business action.

12. Troubleshooting

Columns wrap unexpectedly

Add the Span Columns values. A total above 24 wraps later columns.

Horizontal Alignment appears to do nothing

A row totaling 24 has no free space. Try 8 + 8 while comparing start, center, end, or space-between.

Vertical Alignment appears to do nothing

Use at least two columns with different content heights, or give one column a larger Minimum Column Height.

Form labels look wrong inside a column

Confirm the Grid Column width first, then configure Form. Controls Per Row subdivides the current column, and Form Grid Split is calculated inside each form control region, not against the page's 24 columns.

Design preview and runtime differ

Save the page and confirm runtime uses the current versionId. For data-only differences, check Data Source and Page Context. For width, gap, or alignment differences, confirm the latest Grid properties were saved.