Quick Start
Build a fully functional filterable grid in five steps — create facets, design a card, configure a grid, run the index, and embed the shortcode on any page.
How Grid Panda Works
Grid Panda has four independent building blocks. Understanding their relationship prevents confusion when configuring the plugin:
A facet is one filter dimension — e.g. "Category", "Color", or "Price". It maps to a WordPress taxonomy, post meta key, or WooCommerce attribute. Facets determine the filter UI (checkbox, range, dropdown, etc.) and the WP_Query clause injected when a selection is made.
A card is a reusable HTML template used to render each post inside a grid. Cards are built with a visual block editor — drag in elements like featured image, title, custom fields, price, ratings, badges — and styled per-card with custom CSS.
A grid ties a card template to a post query (post type + filters) and a layout (grid, masonry, list, carousel, etc.). It defines pagination mode, items per page, and which facets are available for filtering.
The index is a pre-built lookup table (wp_gridpanda_index) that stores facet value → post ID mappings. It enables fast facet counts without running expensive WP_Query permutations on every request. The index updates automatically when posts are saved.
POST /wp-json/gridpanda/v1/grids/{id}/render. Grid Panda translates the selections into a WP_Query using each facet type's query-building logic, queries the index table for counts, renders each post through the card template, and returns HTML + pagination + counts.Create Facets
Go to Grid Panda → Facets → Add New. Each facet requires three core settings:
| Setting | What it controls | Example |
|---|---|---|
| Name | Human-readable label shown above the filter widget | Color |
| Type | Filter UI — checkbox, radio, range, dropdown, color, hierarchy, etc. | checkbox |
| Source | Where the values come from — taxonomy, post meta, WooCommerce field, post field | taxonomy:pa_color |
| Post Type | Which post type this facet applies to (for indexing) | product |
The source field uses the format source_type:source_key:
taxonomy:category→ Standard WordPress category taxonomytaxonomy:pa_color→ WooCommerce product attributepost_meta:_price→ WordPress post meta keypost_meta:acf_field_key→ ACF custom fieldpost_field:post_author→ Built-in post field (author, date, status)wc:stock_status→ WooCommerce-specific fieldDesign a Card Template
Go to Grid Panda → Cards → Add New. The card builder is a drag-and-drop block editor. Add blocks to build the layout for each post in your grid:
Each block supports dynamic tags — placeholders that resolve to real post data at render time:
{{post_title}} → Post title
{{post_excerpt}} → Post excerpt (auto-truncated)
{{featured_image}} → <img> tag with thumbnail
{{post_date}} → Formatted publish date
{{post_author}} → Author display name
{{meta:_price}} → Post meta value
{{acf:field_name}} → ACF field value
{{taxonomy:category}} → Comma-joined terms
{{wc:price}} → WooCommerce formatted price
{{wc:rating}} → Star rating (0–5)
{{permalink}} → Full post URLCards also support conditional visibility — hide or show blocks based on post meta, taxonomy membership, WooCommerce stock status, or any dynamic tag value.
Configure a Grid
Go to Grid Panda → Grids → Add New. The grid ties everything together:
Data Source
Choose Post Type and select which post type to query (post, page, product, or any CPT). Set the default orderby, order, and post status. This becomes the base WP_Query for the grid.
Layout
Choose a layout type and configure responsive columns:
Grid
Fixed-column CSS grid — most common
Masonry
Pinterest-style variable height rows
List
Full-width single column rows
Carousel
Horizontal scroll with prev/next
Metro
Mixed tile sizes with a defined pattern
Justified
Equal-height rows with variable width
Facets & Card
Select which facets are available for this grid (you can use any subset of your facets) and which card template renders each post result. Set items per page (default: 12) and pagination mode.
Pagination Modes
numberedClassic prev/next with page numbersload_more"Load More" button appends resultsinfiniteAuto-loads as user scrolls downnoneShows all results without paginationRun the Index
Grid Panda stores facet value → post ID mappings in wp_gridpanda_index for fast count calculations. Go to Grid Panda → Index Status and click Reindex All.
Automatic indexing: After the initial reindex, the index updates automatically whenever:
- A post is published, updated, or deleted
- Terms are added or removed from a post
- Post meta values are added or updated
For large sites (>10,000 posts), indexing runs in batches of 100 posts via the async queue. The Index Status page shows queue depth and per-facet row counts.
Embed on a Page
Use the [gridpanda_grid] shortcode to render the grid anywhere shortcodes are supported. You can reference a grid by its numeric ID or its slug:
<!-- By ID --> [gridpanda_grid id="5"] <!-- By slug --> [gridpanda_grid slug="product-listing"] <!-- Override items per page --> [gridpanda_grid id="5" limit="24"]
To render the filter panel separately from the grid (e.g., in a sidebar or above the grid), use:
<!-- Render specific facets by ID --> [gridpanda_facets ids="1,2,3"] <!-- Render facets filtered by post type --> [gridpanda_facets ids="1,2,3" post_type="product"]
Alternatively, add the Grid Panda Grid Gutenberg block via the block editor, or use the Grid Panda Grid Elementor widget if Elementor is active.