DataCardGrid

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

Use Cases

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

Properties

binding

Query binding for loading card data dynamically from a data query (preferred over dataSource). Type: object.

query

Query name to bind to. Type: string.

field

Field name (optional). Type: string.

isReadOnly

Type: boolean. Default: true.

dataSource

Legacy data source configuration. Prefer ‘binding’ for new implementations. Type: object.

type

Type of data source. Type: string. Options: datasource, pageDataSource, static.

dataSourceId

GUID of the data table (for type: ‘datasource’). Type: string.

dataSourceType

Whether data comes from internal table or external API. Type: string. Options: table, api.

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). NEVER use ID/GUID fields — badges display as visible text labels. Use human‑readable fields like category, type, cuisine, genre. Type: string.

badge2Field

Field for yellow/amber badge (secondary info). NEVER use ID/GUID fields — badges display as visible text labels. Use human‑readable fields like status, tag, difficulty, rating. 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, overlay=image with text overlay. Type: string. Options: elevated, bordered, minimal, overlay. Default: elevated.

imageHeight

Custom image height as CSS value. Overrides imageAspect when set. Type: string.

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.

imageHoverEffect

Image animation on card hover. zoom=scale up, brighten=increase brightness, slideUp=slide image upward. Type: string. Options: none, zoom, brighten, slideUp. Default: none.

enableSearch

Enable search bar + dropdown filters above the card grid. Adds text search and configurable dropdown filters that auto‑populate unique values from data. Type: boolean. Default: false.

searchField

Field name for text search. If blank, searches all text fields. Type: string.

searchPlaceholder

Placeholder text for the search input. Type: string.

filters

Array of dropdown filter definitions. Each filter auto‑populates unique values from the specified data field. Users can add as many filters as needed. Type: array.

field

Data field name to filter by. Unique values are auto‑extracted. Type: string.

label

Label for the ‘All’ option in the dropdown (e.g., ‘All Categories’). Type: string.

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
• Use enableSearch with filters array for browsable collections (e.g., filters: [{ field: 'category', label: 'All Categories' }])
• Use imageHoverEffect='zoom' for visual polish on image‑heavy grids

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)

Using binding without mapping imageField, descriptionField, subtitleField

Why it's a problem: Cards render with only a title — no images, descriptions, or visual content. Looks broken and empty.

Fix: When using binding, ALWAYS map: imageField, titleField, descriptionField at minimum. Also add subtitleField, badge1Field, metaField1 for richer cards.

Not adding onCardClick for navigation to detail pages

Why it's a problem: Users see cards but can’t click to see details. Cards are non‑interactive dead ends.

Fix: Add onCardClick: "context.navigate('detail-page?id=' + context.item.id);" to link cards to detail pages.

Using DataCardGrid for e‑commerce product listings instead of ShoppingCart

Why it's a problem: DataCardGrid has no add‑to‑cart, no cart sidebar, no checkout. Users browse products but cannot purchase. ShoppingCart handles product grid + category filtering + floating cart + checkout in ONE component.

Fix: Use ShoppingCart for any page where users shop/buy products. DataCardGrid is for non‑commerce browsing: recipes, portfolios, blogs, real estate listings, team profiles.

Mapping ID/GUID fields to badge1Field or badge2Field

Why it's a problem: Badges render as visible text labels on the card. A GUID like '3f2504e0-4f89-11d3-9a0c-0305e82c3301' is meaningless to users and looks broken.

Fix: Only use human‑readable categorical fields for badges: category, type, status, cuisine, genre, difficulty, rating. Leave badge fields empty if no suitable field exists.