Power Plus - Renderer Grid

The Grid Renderer displays data in a structured columns-and-rows layout using CSS Grid. It includes a header row with column titles, optional footer rows, and supports row grouping. Unlike the Block renderer (which arranges cards in a freeform layout), the Grid renderer produces a strict tabular structure where every item occupies exactly one row and every field occupies a defined column.

The Grid renderer is best for data-heavy views where visitors need to compare items across multiple attributes — shopping carts with quantities and prices, product comparison tables, data dashboards, and administrative lists. The Wishlist use case demonstrates both a CartRenderer (extending Grid for the shopping cart) and a RecommendedProductsRenderer (extending Grid for cross-sell suggestions).

Configuration

Field	Type	Description
Name	Text	A unique identifier (e.g. `cart_renderer`, `comparison_grid`). The List module references this name.

Fields (Repeating Group)

Each field defines a column in the grid. The order of fields determines the left-to-right order of columns.

Field Property	Description
Name	A CSS class suffix for styling. `price` produces class `pwr-list-field-price` on the column cells. This lets you target specific columns in custom CSS (e.g. right-align price columns, bold the name column).
Title	Rich text for the header cell. This is the column heading shown in the top header row. Supports JSONata for dynamic headers. Example: `<strong>Product</strong>` or `Price (€)`.
Display	The HTML element type for cells in this column. `text` — a `<div>` with your content template. `image` — an `<img>` tag. `input` — a form input (text, number, etc.) — useful for editable grids like the cart’s quantity field. `link` — an `<a>` tag.
Value	A JSONata expression for the data value. Used for `image` (as the `src` URL) and `input` (as the default value).
Content	Rich text with embedded JSONata for `text` display. Example: `<span class="pwr-list-grid-body-item__title">[[object.name]]</span>`.
Width	CSS width for this column. Uses CSS Grid syntax (see Column Width System below).
Show Footer	Whether to render content in the footer row for this column. Used for totals, summaries, or action buttons.
Footer Content	Rich text for the footer cell. Supports JSONata with access to aggregate data.
Link	Makes cells in this column clickable. Set the URL (JSONata), target, and rel attributes.
Alt Text	For image columns only. The alt text expression.

Grouping

Row grouping lets you organize data into collapsible or visually separated sections based on a shared property.

Field	Description
Enable Grouping	When checked, rows are grouped by a data field. A group header row is inserted before each group.
Group By	A JSONata expression that returns the grouping key. Items with the same key value are placed in the same group. Example: `object.category` groups rows by their category.
Content	Rich text template for group header rows. Supports JSONata. Example: `<h3>[[object.category]]</h3>`.
Render Header	Whether to show the column header row inside each group (repeating the column titles).

Layout Options

Field	Default	Description
Items Per Page	25	Number of rows per page before “Load More”. Grids typically show more items per page than cards because rows are compact. 25–50 is common.
Spacing	`default`	Gap between rows. `default` uses the theme’s standard spacing; `none` removes all gaps for a tighter table look.
Mobile Mode	`none`	How the grid adapts to small screens. `none` — grid stays as-is (may overflow the viewport). `scroll_hori` — the grid becomes horizontally scrollable (a scrollbar appears). `stack_rows` — each row transforms into a vertical card showing label-value pairs (the header titles become labels). See Mobile Modes below.

Visual Style

Style	Description
`default`	Clean grid with alternating row backgrounds for readability (zebra striping).
`product-cart`	Shopping cart design: product image thumbnails, quantity inputs, price columns, delete buttons, and a footer row with the total price. Designed for the Wishlist/Cart use case.
`product-border`	Bordered rows with product image thumbnails and text columns. Subtler than the cart style — good for recommendation lists or order summaries.
`custom`	Use a custom CSS file for complete design control.

Advanced

Field	Description
Renderer	The JavaScript renderer class. Default: `GridRenderer`. Override for custom behavior. Examples: `CartRenderer` (adds quantity handlers, delete buttons, total price calculation) and `RecommendedProductsRenderer` (adds “Add to Wishlist” buttons that update the cart).

Examples

Wishlist / Shopping Cart

The most complex Grid renderer example — a full shopping cart with editable quantities, delete buttons, and a running total:

Renderer Module:
  Name: wishlist_renderer
  Style: product-cart
  Advanced Renderer: CartRenderer
  Fields:
    - Name: product-img
      Display: image
      Value: [[ object.hs_images ? object.hs_images.$split(',')[0] : '' ]]
      Width: 120px
      Link: /product/[[object.hs_sku]]
    - Name: product-title
      Display: text
      Content: <span class="pwr-list-grid-body-item__title">[[object.name]]</span>
      Width: 1fr
    - Name: quantity
      Display: input
      Input Type: number
      Value: [[object.quantity]]
      Width: 120px
    - Name: price
      Display: text
      Content: [[object.hs_price_eur]]€
      Width: 160px
    - Name: btn-del
      Display: text
      Content: (empty — rendered by CartRenderer)
      Width: 40px

The CartRenderer extends GridRenderer to add behavior that cannot be configured through module fields: - A footer row with a total price that sums price × quantity across all items. - Quantity change handlers — when the visitor changes a number input, the cart is updated in localStorage and the total recalculates. - Delete buttons — each row gets a trash icon that removes the item from the cart. - Real-time recalculation — prices update instantly as quantities change, without a page reload.

Recommended Products

A secondary grid on the Wishlist page showing products the visitor might also want:

Renderer Module:
  Name: product_renderer
  Style: product-border
  Advanced Renderer: RecommendedProductsRenderer
  Fields:
    - Name: product-img
      Display: image
      Value: [[ object.hs_images ? object.hs_images.$split(',')[0] : '' ]]
      Alt Text: [[ object.name ]]
    - Name: product-title
      Display: text
      Content: <span class="pwr-list-grid-body-item__title">[[object.name]]</span>
    - Name: btn-add-to-wishlist
      Display: text
      Content: <div class="pwr-product-2-cart-btn pwr-product-2-cart-btn--btn-onetime">Add To Wishlist</div>
    - Name: price
      Display: text
      Content: [[ $formatNumber(object.hs_price_eur, "#,##0.00") ]]€

The RecommendedProductsRenderer adds click handlers to the “Add To Wishlist” buttons. When clicked, the product is added to the cart stored in localStorage, and the main wishlist list refreshes to include the new item.

Simple Data Grid

A basic, read-only data grid with column headers and responsive mobile stacking:

Renderer Module:
  Name: data_grid
  Style: default
  Items Per Page: 50
  Mobile Mode: stack_rows
  Fields:
    - Name: name
      Title: <strong>Name</strong>
      Display: text
      Content: [[object.name]]
      Width: 2fr
    - Name: category
      Title: Category
      Display: text
      Content: [[object.category]]
      Width: 1fr
    - Name: price
      Title: Price
      Display: text
      Content: [[ $formatNumber(object.price, "#,##0.00") ]]€
      Width: 100px
    - Name: date
      Title: Date
      Display: text
      Content: [[ $fromMillis(object.createdate, "[D01]/[M01]/[Y0001]") ]]
      Width: 120px

Column Width System

Column widths are set using CSS Grid’s grid-template-columns syntax. You define a width for each column, and the grid engine distributes space accordingly.

Width Value	Meaning	When to Use
`1fr`	Takes 1 fractional unit of remaining space	Flexible columns that should share available space equally
`2fr`	Takes 2 fractional units (twice as wide as `1fr`)	Columns that need more space (like names or descriptions)
`120px`	Fixed width of exactly 120 pixels	Images, action buttons, short numeric values
`auto`	Width determined by content	Columns where content width varies but you want a snug fit
`minmax(100px, 1fr)`	Minimum 100px, expands up to 1 fraction	Columns that should be flexible but never too narrow

Example: 120px, 1fr, 120px, 160px, 40px creates a grid with a fixed-width image column, a flexible name column, a fixed quantity column, a fixed price column, and a narrow button column.

Mobile Modes

On small screens, multi-column grids can become unusable. The Mobile Mode setting provides three strategies:

Mode	Behavior	Best For
`none`	The grid stays in its desktop layout. If it’s wider than the screen, it overflows (no scrollbar).	Simple grids with few, narrow columns that fit on mobile.
`scroll_hori`	The grid becomes horizontally scrollable. A scrollbar appears at the bottom.	Data-heavy grids where all columns need to remain visible (e.g. comparison tables).
`stack_rows`	Each row transforms into a vertical “card” showing label-value pairs. The column titles become labels for each value.	User-facing grids where readability is more important than the tabular layout.

Visual comparison:

Grid Mobile Stacking

Table vs Grid: When to Choose Which

Feature	Table Renderer	Grid Renderer
HTML structure	Semantic `<table>`, `<tr>`, `<td>`	CSS Grid with `<div>` elements
Footer row	Semantic `<tfoot>`	Custom footer `<div>`
Row grouping	Not supported	Supported
Input fields	Supported	Supported (used for cart quantities)
Custom renderer classes	Supported	Supported (CartRenderer, etc.)
Accessibility	Native table semantics (better for screen readers)	Requires ARIA attributes
Best for	Simple, read-only data tables; SEO-friendly markup	Complex interactive layouts; carts; grouped data

Choose the Grid Renderer when you need grouping, footer calculations, interactive inputs, or custom renderer classes. Choose the Table Renderer for simple read-only tables where semantic HTML matters.