Grid

Responsive grid layout component that arranges child components in equal‑width columns. It automatically stacks to a single column on mobile devices, making it ideal 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 are 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: Forms – use 2 columns; Cards – use 3 columns; Dashboards – use 4 columns; Single‑column – use 1 column for full‑width stacking.

gap

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

Tip: Forms – use 16‑24 px for balanced spacing; Cards – use 24‑32 px for visual breathing room; Compact – use 12‑16 px; Spacious – use 32‑48 px for an airy feel.

items

Array of child components to arrange in grid columns. Components are 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.

Tip: Add background colors or gradients to visually group sections; add padding for separation from other content; use border‑radius for a modern card‑like appearance.

Best Practices

• CRITICAL: Use Grid for form layouts to avoid stacking all fields at full width
• CRITICAL: ALWAYS set gap: 24 (or 16‑32 px) – 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.