Skip to main content

Grid Mode

modeConfig.grid tiles items into a responsive card grid. Use grid when card-based browsing matters more than dense row scanning.

Shared Behavior​

Pagination, search, static filtering, actions, gestures, and groupings work the same as other modes — see the reference pages:

Core Examples​

Responsive Grid (Baseline)​

This baseline emphasizes responsive wrapping with clear defaults for card width and maximum columns.

A straightforward grid with fixed minimum card width and a capped column count.

Name:Aurora Chen
Role:Design Lead
Status:active
Team:Design
Name:Mateo Silva
Role:Platform Engineer
Status:pending
Team:Platform
Name:Priya Nair
Role:Operations
Status:inactive
Team:Operations
Name:Samir Khan
Role:QA
Status:active
Team:Platform
Name:Leah Wong
Role:Customer Success
Status:active
Team:Operations
Name:Iris Patel
Role:Analytics
Status:pending
Team:Design
Name:Jonas Bell
Role:Support Engineer
Status:active
Team:Operations
Name:Niko Reyes
Role:UX Researcher
Status:inactive
Team:Design
modeConfig: {
  grid: {
    minItemWidth: '230px',
    maxColumns: 4,
    gap: '1rem',
  },
}

Masonry Layout​

Masonry packing is most visible when card heights vary naturally. Here each card contains a single image at its natural aspect ratio.

Uses layoutMode='masonry' with cards of varying heights to produce a waterfall layout.

imageUrl
imageUrl
imageUrl
imageUrl
imageUrl
imageUrl
imageUrl
imageUrl
modeConfig: {
  grid: {
    layoutMode: 'masonry',
    minItemWidth: '180px',
    maxColumns: 4,
    gap: '0.75rem',
  },
}
// Image field — natural aspect ratios drive card heights:
item: {
  fields: [
    {
      key: 'imageUrl',
      label: '',
      type: 'image',
      imageOptions: { width: '100%', height: 'auto', objectFit: 'cover', borderRadius: 6 },
    },
  ],
}

Alignment Controls​

Use the alignment controls when card width, spacing, or packing needs to be tuned beyond the defaults.

Centers narrower cards inside each grid cell to make justifyItems and alignItems behavior visible.

Name:Aurora Chen
Role:Design Lead
Status:active
Name:Mateo Silva
Role:Platform Engineer
Status:pending
Name:Priya Nair
Role:Operations
Status:inactive
Name:Samir Khan
Role:QA
Status:active
Name:Leah Wong
Role:Customer Success
Status:active
Name:Iris Patel
Role:Analytics
Status:pending
Name:Jonas Bell
Role:Support Engineer
Status:active
Name:Niko Reyes
Role:UX Researcher
Status:inactive
modeConfig: {
  grid: {
    minItemWidth: '280px',
    maxColumns: 3,
    gap: '1.25rem',
    justifyItems: 'center',
    alignItems: 'start',
  },
}
item: {
  style: { maxWidth: '210px', width: '100%' },
}

Grouping in Grid​

zones.content.groupings also applies to grid mode. In grid, grouping controls are rendered as grouped sections (not table header controls).

Groups cards by team with collapsible group sections and a custom group label renderer.

Design team · 3 members ▼ (3)
Name:Aurora Chen
Role:Design Lead
Status:active
Team:Design
Name:Iris Patel
Role:Analytics
Status:pending
Team:Design
Name:Niko Reyes
Role:UX Researcher
Status:inactive
Team:Design
Platform team · 2 members ▼ (2)
Name:Mateo Silva
Role:Platform Engineer
Status:pending
Team:Platform
Name:Samir Khan
Role:QA
Status:active
Team:Platform
Operations team · 3 members ▼ (3)
Name:Priya Nair
Role:Operations
Status:inactive
Team:Operations
Name:Leah Wong
Role:Customer Success
Status:active
Team:Operations
Name:Jonas Bell
Role:Support Engineer
Status:active
Team:Operations
zones: {
  content: {
    groupings: [
      {
        fieldKey: 'team',
        collapsible: true,
        renderer: (groupValue, count, isCollapsed) =>
          `${groupValue} team · ${count} members ${isCollapsed ? '▶' : '▼'}`,
      },
    ],
  },
}

Search and Filtering​

A search bar renders above the grid when config.search is enabled. Static filtering pre-excludes records before render — the grid simply shows fewer cards. This example pre-excludes inactive members and adds a live search over name, role, and team.

Search bar above the card grid with a static filter pre-applied to exclude inactive members.

Name:Aurora Chen
Role:Design Lead
Status:active
Team:Design
Name:Mateo Silva
Role:Platform Engineer
Status:pending
Team:Platform
Name:Samir Khan
Role:QA
Status:active
Team:Platform
Name:Leah Wong
Role:Customer Success
Status:active
Team:Operations
Name:Iris Patel
Role:Analytics
Status:pending
Team:Design
Name:Jonas Bell
Role:Support Engineer
Status:active
Team:Operations
zones: {
  content: {
    search: {
      enabled: true,
      fields: ['name', 'role', 'team'],
      placeholder: 'Search members...',
    },
    filtering: [
      { fieldKey: 'status', operator: 'ne', value: 'inactive' },
    ],
  },
}

See Also​