Grid

Responsive grid layout component that arranges child components in equal‑width columns and automatically stacks on mobile devices. It is essential for professional multi‑column form layouts and card grids.

Use Cases

• Multi‑column form layouts (2‑3 fields per row on desktop)
• Card grids for features, products, or services
• Dashboard layouts with multiple sections
• Responsive layouts that stack on mobile
• Equal‑width column layouts (all columns same width)

Properties

numColumns

Number of equal‑width columns in the grid. All items distributed evenly across columns. Type: number. Options: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12. Default: 2. Visual Impact: Determines grid layout – 2 = two equal columns (50% each), 3 = three columns (33% each), etc. Auto‑stacks to 1 column on mobile.

Tip: Recommendations – forms: Use 2 columns for most form layouts (Company + Job Title, First Name + Last Name); cards: Use 3 columns for card grids (features, products, team members); dashboards: Use 4 columns for dashboard widgets or statistics; single‑column: Use 1 column when you need full‑width stacking.

gap

Spacing between grid items in pixels (both horizontal and vertical gaps). Type: number. Default: 24. Visual Impact: 0 – no gap (items touch); 8 – very tight spacing; 12 – tight spacing; 16 – compact spacing; 24 – balanced spacing (recommended default); 32 – generous spacing; 48 – very generous spacing.

Tip: Recommendations – forms: Use 16‑24px for balanced form field spacing; cards: Use 24‑32px for card grids with visual breathing room; compact: Use 12‑16px for compact layouts; spacious: Use 32‑48px for airy, premium feel.

items

Array of child components to arrange in grid columns. Components automatically distributed across numColumns. Type: slot. Required: true. Minimum items: 1.

customCss

Custom CSS styles for advanced styling of the grid container. Parsed as CSS property‑value pairs. Type: string. Default: none.

Tip: Recommendations – backgrounds: Add background colors or gradients to visually group grid sections; spacing: Add padding to create visual separation from other content; borders: Use border‑radius for modern card‑like appearance.

Security Note: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

Best Practices

• CRITICAL: Use Grid for form layouts to avoid stacking all fields at full width
• CRITICAL: ALWAYS set gap: 24 (or 16‑32px) – without gap, fields touch each other with no spacing (looks unprofessional)
• Use numColumns: 2 for typical form layouts (Company + Job Title, Email + Phone, etc.)
• Use numColumns: 3 for card grids and feature showcases
• Group logically related fields together (name fields, contact fields, date fields)
• Keep forms scannable – max 2‑3 fields per row on desktop
• Grid automatically stacks to 1 column on mobile – no additional config needed

Common Mistakes

Using Grid WITHOUT setting gap property

Why it's a problem: Fields touch each other with no spacing – looks cramped, unprofessional, hard to read

Fix: ALWAYS set gap: 24 for balanced spacing: {numColumns: 2, gap: 24}

Not using Grid for form layouts - stacking all fields at full width

Why it's a problem: Creates long, monotonous forms that waste horizontal space and feel unprofessional

Fix: Wrap related form fields in Grid with numColumns: 2 AND gap: 24

Using too many columns (numColumns: 4+) for forms

Why it's a problem: Fields become too narrow on desktop, labels truncated, forms hard to scan

Fix: Use numColumns: 2 for forms, numColumns: 3 max for cards/features

Mixing unrelated fields in same Grid

Why it's a problem: Breaks logical grouping – users expect related fields together (name fields, contact fields, dates together)

Fix: Create multiple Grid components, each grouping logically related fields

Putting TextArea or long text fields in multi‑column Grid

Why it's a problem: TextArea needs full width for comfortable editing – looks cramped in narrow columns

Fix: Place TextArea, RichText, and long description fields OUTSIDE Grid at full width

Using excessive gap values (48px+) for forms

Why it's a problem: Excessive spacing makes forms feel disconnected and harder to scan

Fix: Use gap: 16‑24 for forms, gap: 24‑32 for card grids

Using Grid with Image components to create a photo gallery

Why it's a problem: Grid + Image loses lightbox zoom, hover effects, captions, masonry layout, and responsive behavior that PhotoGallery provides out of the box. The result looks amateur and static.

Fix: ALWAYS use the PhotoGallery component for any image gallery, photo showcase, or image collection. PhotoGallery has built‑in masonry/grid layouts, lightbox viewer, captions, and hover effects.

Using numColumns: 12 with CSS grid-column: span N in child customCss to create split layouts

Why it's a problem: Child customCss is applied INSIDE the grid cell wrapper, not ON the grid cell itself. CSS grid-column has NO effect because it’s not on a direct grid child. Result: each item gets 1/12 width (tiny).

Fix: Use numColumns matching the number of items (numColumns: 2 for 50/50 split, numColumns: 3 for thirds). Grid distributes items evenly across equal‑width columns. For hero sections, use the Hero component instead of Grid + Image.

Using Grid + Image + Flex to build a hero section instead of using the Hero component

Why it's a problem: The Hero component provides proper hero layouts (side‑by‑side, background image, overlays, CTA buttons, responsive) out of the box. DIY Grid layouts produce tiny images and broken layouts.

Fix: ALWAYS use the Hero component for hero sections. Use backgroundEffect.imageMode='inline' for side‑by‑side or 'background' for full‑width image backgrounds.