DataCardGrid

A visual card‑based grid for displaying data. Ideal for consumer‑facing content where visual discovery matters, such as recipes, products, portfolios, and similar collections. Use it instead of DataGrid when browsing or discovering items is more important than managing data.

Use Cases

• Recipe collections with food images
• Product catalogs for e-commerce
• Portfolio/gallery displays
• Blog post listings
• Real estate property listings
• Team member profiles
• Event listings
• Any content where visual appeal drives engagement

Properties

dataSource

Data source configuration for the grid. Type: object.

imageField

Field name for card image URL. Use search_unsplash to populate with contextual images. Type: string.

titleField

Field name for card title (the main text). Type: string. Required.

subtitleField

Field name for subtitle text below the title. Type: string.

attributionField

Field for attribution/source text (italic). Great for “From Grandma’s kitchen” or “By Chef John”. Type: string.

descriptionField

Field for longer description text. Type: string.

badge1Field

Field for orange badge (category/type). Displayed prominently. Type: string.

badge2Field

Field for yellow/amber badge (secondary info). Type: string.

metaIcon1

Icon for first metadata field. clock=time, users=servings/people, star=rating, tag=category. Type: string. Options: none, clock, users, star, tag. Default: none.

metaField1

Field for first metadata value (pairs with metaIcon1). Type: string.

metaIcon2

Icon for second metadata field. Type: string. Options: none, clock, users, star, tag. Default: none.

metaField2

Field for second metadata value (pairs with metaIcon2). Type: string.

metaBadgeField

Field for outline badge in metadata row (difficulty/skill level). Type: string.

columns

Number of columns in the grid. 2=detailed, 3=balanced, 4=compact. Type: number. Options: 2, 3, 4. Default: 3.

cardStyle

Card visual style. elevated=shadow, bordered=outline, minimal=flat. Type: string. Options: elevated, bordered, minimal. Default: elevated.

imageAspect

Image aspect ratio. landscape (16:10), square (1:1), portrait (3:4), none (no image). Type: string. Options: landscape, square, portrait, none. Default: landscape.

onCardClick

JavaScript code executed when card is clicked. Use context.item for row data, context.navigate() for navigation. Type: string.

enablePagination

Enable pagination controls below the grid. Type: boolean. Default: true.

pageSize

Number of items per page. Choose multiples of columns for even rows. Type: number. Options: 6, 9, 12, 15, 18, 24. Default: 9.

customCss

Custom CSS styles for the grid container. Type: string.

Best Practices

• Always include imageField for visual impact – use search_unsplash to get contextual images.
• Map titleField to the primary identifier (name, title).
• Use badge1Field for category/type, badge2Field for status/secondary info.
• Use metaIcon1/metaField1 for metrics like time, servings, price.
• Set columns based on content: 2 for detailed cards, 3 for balanced, 4 for compact.
• Choose cardStyle based on design: elevated for modern, bordered for clean, minimal for flat.
• Always configure onCardClick to navigate to detail page.
• Use imageAspect='landscape' for most content, 'square' for products, 'portrait' for people.

Common Mistakes

Using DataCardGrid for admin/management interfaces

Why it's a problem: DataCardGrid is for browsing/discovery, not data management

Fix: Use DataGrid for admin interfaces where users edit, filter, or manage data

Not including imageField when images are available

Why it's a problem: DataCardGrid’s main value is visual browsing – without images it loses impact

Fix: Add image_url column to data table, use search_unsplash to populate with contextual images

Using context.row instead of context.item in onCardClick

Why it's a problem: DataCardGrid uses context.item (not context.row like DataGrid)

Fix: Use context.item.id, context.item.title, etc. in onCardClick scripts

Setting pageSize that doesn’t divide evenly by columns

Why it's a problem: Creates uneven last row – looks unpolished

Fix: Set pageSize to multiple of columns (e.g., columns=3, pageSize=9 or 12)