InstantFilter docs

Quick start

InstantFilter runs directly inside WooCommerce. You configure filters under WP Admin → InstantFilter, index your catalog, and drop a shortcode or native Bricks element onto your shop or landing page.

1. Start your trial and install

1. Download the free 14-day trial (no credit card required) or choose a plan on our pricing page.
2. Download the plugin zip from your confirmation email.
3. In WordPress: Plugins → Add New → Upload Plugin, then activate InstantFilter.
4. Navigate to InstantFilter → License and paste your license key. The remaining tabs stay locked until your key validates.

2. Reload Products

Click Reload Products in the admin header (or inside step 1 of the wizard). This populates the wp_if_items table with your WooCommerce catalog. After this initial run, InstantFilter keeps the items table synchronized automatically whenever you save, edit, or delete products — you only need to reload manually after large bulk imports or if you notice discrepancies between WooCommerce and your indexed item count.

3. Add filters

Navigate to the Filters tab and click Add Filter. The modal covers source, reference, label, and display type:

• Source — where filter data originates (taxonomies, attributes, custom meta fields, ACF, or the Filter repeater to generate filters for all attributes automatically).
• Reference — the specific taxonomy or attribute key (e.g. pa_color, product_cat).
• Filter Name — the storefront label shoppers see in the sidebar.
• Display Type — checkbox, color swatch, range slider, dropdown, radio, rating, toggle, etc.

Save and repeat for each filter you want in the sidebar. See Filters for the complete field reference.

4. Update Filters & choose a card layout

Click Update Filters in the admin header. InstantFilter indexes every enabled filter against your catalog and builds the JSON export files (with Auto Build Exports enabled by default) for high-performance client-side filtering.

Under InstantFilter → Layouts, click Card templates to select a ready-made layout preset (Classic, Catalog, Showcase, or Lifestyle) for your universal archive. With a Pro or Agency license, you can customize these templates with the visual StyleBuilder.

5. Place a shortcode or Bricks element

Add the archive to any page, category template, or page builder block:

[instant_archive]

Building with Bricks Builder? Drag the native IF — Sidebar + Grid element directly into your layout or WooCommerce archive template — no shortcodes required. See our Bricks Builder documentation.

This renders the complete store experience: filter sidebar, responsive product grid, toolbar with sorting, and pagination. Initial page loads are server-rendered for SEO; once hydrated, filter selections resolve instantly in the browser.

Explore Filters for detailed field configurations, Listings for curated collections, Card loops for standalone product grids, Layouts & StyleBuilder for card styling, and Bricks Builder for native builder integration.

How indexing works

InstantFilter decouples which products exist from how shoppers can filter them and what the browser downloads. The architecture relies on three dedicated layers, each paired with an admin action:

Delta sync — automatic updates without manual rebuilds

Once you run Reload Products for the first time, InstantFilter maintains the items table automatically through core WordPress hooks. Creating, updating, trashing, or restoring a product immediately triggers a targeted delta update that touches only the affected rows — avoiding heavy full catalog rebuilds.

You only need to click Reload Products manually when:

• You perform a bulk import outside standard WordPress lifecycle hooks (CSV imports, WP All Import, external REST API syncs).
• You notice a discrepancy between WooCommerce catalog numbers and the InstantFilter Items count.
• You adjust variation explode rules and want to verify the entire card index.

For standard store management, delta synchronization ensures your index remains up to date automatically.

Admin status indicator

The status pill adjacent to the header buttons reflects your current index state:

• No products loaded — initial setup; click “Reload Products”.
• X of Y filters active — filter definitions have changed; click “Update Filters”.
• X filters active — index is up to date and ready for the storefront.
• No filters created — add at least one filter on the Filters tab.

When to run Update Filters

• After adding, modifying, disabling, or reordering filters.
• After generating filters via the Filter repeater (which scans the catalog for attributes).
• After modifying variation explode rules to ensure facet counts align with card splits.

Export files regenerate automatically whenever Auto Build Exports is active (recommended). The manual “Build Export” button is only displayed when WordPress debug mode (WP_DEBUG) is enabled.

Server-side rendering (SSR) vs. client-side speed

Shoppers receive complete, semantic HTML on their first page visit (SSR), ensuring search engine crawlers and screen readers access full product content instantly. Compressed exports download concurrently in the background; once hydrated, user clicks resolve completely in memory without hitting your database or PHP workers. Items, filters, and exports should all be compiled before auditing performance on staging.

Per-archive exports & compact card payloads

To deliver peak performance across expansive enterprise catalogs, InstantFilter splits export payloads intelligently:

• Per-archive exports: Rather than downloading the entire store catalog on every archive, InstantFilter can compile smaller, dedicated export shards for category, tag, and attribute pages (configurable in Settings). A shopper browsing /product-category/running-shoes/ downloads only products within that specific category.
• Dedicated card shards (cards.json.gz): Extended product card data (such as custom meta attributes and wishlist states) loads via compressed gzip shards instead of heavy inline HTML script tags, keeping your initial DOM exceptionally clean.
• Search archives (?s=): When visitors search, InstantFilter creates an optimized subset file on the first query that is subsequently cached and served instantly for identical searches.

License

Navigate to InstantFilter → License (admin.php?page=if-admin&tab=license).

Activate your key

1. Paste the license key from your purchase confirmation or trial activation email.
2. Click “Activate”. The plugin validates against InstantStack servers and unlocks Filters, Variations, Listings, Card loops, Layouts, and Settings.
3. Until a valid key is activated, all other tabs remain locked and inaccessible.

Trial workflow

You can request a 14-day trial directly from our website with zero payment details required. Trial licenses (prefixed with TRIAL-...) are verified and managed directly via our own InstantFilter licensing infrastructure. Paid commercial licenses are fulfilled and managed through Lemon Squeezy.

What your tier controls

Limits reflect our Founders pricing tiers. If you exceed catalog or listing limits, indexing buttons indicate “Limit reached” until you upgrade.

Deactivating or moving licenses

Click “Deactivate License” on the License tab before moving to a new domain or staging environment, then re-activate on your new site. For billing, upgrades, or refund details, see our FAQ.

Filters (Filter Definitions)

InstantFilter → Filters is where you define which facets appear in your shop sidebar. Each row represents a distinct filter. Active filters are compiled into your index when you click Update Filters.

Filter Definitions table

• Active — toggle switch to include or exclude a filter from indexing and frontend rendering.
• Filter Name — the public label shoppers see in the sidebar.
• Source — the data origin (General (WooCommerce), Taxonomy, Global/Custom Attributes, Meta Field, ACF Field, Filter repeater, etc.).
• Type — facet display type (checkbox, range slider, color swatch, dropdown, radio, rating, toggle, etc.).
• Actions — edit, delete, or copy the standalone shortcode [instant_filter prop="…"].

Drag rows vertically to adjust sidebar filter order. Attributes generated via the Filter repeater appear neatly nested under their repeater parent.

Filter repeater (Automatic attribute filters)

Instead of manually configuring dozens of individual attribute filters, use the Filter repeater to discover and create them in bulk:

• Filter repeater – global attributes — scans your catalog and automatically provisions a child filter for every global WooCommerce attribute (pa_*).
• Filter repeater – custom attributes — accomplishes the same for custom product attributes configured directly on products.

When you save a Filter repeater definition, InstantFilter generates all child filters automatically. Run Update Filters once generation completes. Use Exclude Attributes (one attribute key per line) to skip technical or internal attributes you prefer not to display.

Storefront presentation: each discovered attribute renders as its own filter block in your sidebar, respecting your drag-and-drop order.

Add Filter dialog — field reference

Click Add Filter to open the modal. Core fields include:

Hierarchy & exclusions (Category tree structure)

For hierarchical taxonomies (such as WooCommerce product categories), providing clear structure is vital for smooth navigation. InstantFilter provides advanced hierarchical controls and term isolation:

• Visual tree indentation: Enabling “Show Child Terms” renders child categories indented beneath their parent. Parent terms are emphasized in bold, accompanied by subtle vertical branch indicators. Indentation width is customizable via the CSS variable --if-category-indent (defaults to 20px).
• Configurable nesting depth: Specify exact nesting limits. A depth of 1 displays immediate subcategories only, whereas higher values reveal deeper branches. Flat taxonomies (like tags or brands) automatically hide this option.
• Contextual archive isolation: When a customer navigates to a specific category page (e.g. /product-category/clothing/), InstantFilter automatically isolates the filter to display only subcategories of Clothing. The current category itself, ancestor categories, and sibling categories remain hidden to preserve relevant, clutter-free browsing.
• Group protection under limits: The global “Max Values Per Filter” setting counts only top-level items in nested trees, preventing sub-branches from being awkwardly severed mid-list.
• Excluding unwanted terms: Need to hide internal or seasonal categories (like “Sale Banners”, “Archived”, or “Uncategorized”)? Add them via the Exclude terms picker and optionally tick “Also exclude child terms”. After re-indexing, excluded terms are completely removed from both HTML and export payloads.

See Variations for catalog-wide explosion rules and Settings for global sidebar thresholds.

Variations

Variable products are WooCommerce’s standard mechanism for offering a single parent item in multiple variations — sizes, colors, finishes. By default, stores render the parent product as a single card with a broad price range. Exploding a variation attribute splits that single card into distinct individual cards, one for each variation. This turns “Nike Air Force 1” from one generic card into three distinct cards for black, white, and blue.

Visual comparison

One variable product with three color variations. The top row illustrates standard parent product rendering; the bottom row demonstrates the same product with color exploded:

Display modes

Configuration points

You can configure variation explosion in two places — both synchronize to the same centralized rule registry:

1. Filters → Add/Edit Filter → Advanced Settings. When a filter source is an attribute (such as pa_color), the modal offers a Variation Display Mode control. Use this when you want an attribute to serve as both a sidebar facet and an explosion rule.
2. Variations tab → Add attribute. Use this when you want to explode variations by an attribute without exposing it as an interactive sidebar facet. For example: explode products by color while omitting color from the filter sidebar.

Attributes governed by a filter definition display a Via filter badge on the Variations tab and remain synchronized whenever you adjust the filter. Standalone entries are managed directly on the Variations tab.

Sub-parents during partial explosion

Footwear typically features both color and size attributes. If you explode on color but leave size grouped, InstantFilter creates one card per color — a sub-parent that encapsulates all available sizes for that color:

• Red — sizes 7, 8, 9
• Blue — sizes 7, 8, 9
• etc.

These sub-parents are not separate WooCommerce post records. They exist within InstantFilter’s compiled index to allow the grid to present one cohesive card per exploded attribute. In WooCommerce, the underlying variations remain the specific size and color combinations:

• Red, size 7
• Red, size 8
• Red, size 9

Each carries its own variation record in WooCommerce — including individual image fields. The sub-parent card draws its image dynamically from child variations. The image displayed corresponds to the imagery configured on those variation rows.

Best practice in WooCommerce: Assign images to every variation row, prioritizing photography that highlights the exploded attribute. For color explosion + grouped sizes, every red variation should feature a photo of the red shoe, regardless of size:

• Red, size 7 → red shoe photo
• Red, size 8 → red shoe photo
• Red, size 9 → red shoe photo

Repeat consistently for blue, green, and other colors. If variation rows under the same color use differing imagery, the sub-parent displays whichever image the indexer encounters first — keep imagery consistent across matching variants.

Smart variation pricing & automatic sale badges

InstantFilter inspects variation pricing automatically to ensure clarity for shoppers:

• Explicit pricing for matching variants: If all sizes or options of a product share the same regular and sale prices, the card clearly displays both the original strikethrough price and the discounted price (e.g. $89.95 $69.95). Only when variation prices genuinely differ from one another does the card show “From $…”.
• Automatic sale badge: The sale badge appears on a product card automatically whenever at least one active variation is on sale.
• Consistent term archives: Exploded variations are indexed directly under their specific attribute terms. A red sneaker variant immediately displays on the red color archive page, while the unexploded parent remains hidden as long as variation explosion is active.

Storefront presentation: Product grids render parent cards, sub-parents, or individual variation cards based on your configuration; filter facets accurately reflect exploded items rather than parent-level totals.

Listings

A listing is a curated product collection paired with its own shortcode and (optionally) a distinct filter configuration. Use listings when a single general shop page is insufficient — promotional landing pages, dedicated brand shops, in-stock inventories, or B2B product subsets.

Universal Archive (system listing, ID -1)

Every install includes a built-in system listing that dynamically mirrors WooCommerce archive contexts. Place its shortcode on any standard WooCommerce archive template and it detects its environment automatically:

• On your main shop page — all indexed products and the full set of filters.
• On a category archive — products scoped to that category, with facets and counts adapted to context.
• On a tag archive — scoped strictly to items carrying that tag.

Shortcode: [instant_archive]

Custom listings

Click Add Listing on the Listings tab. The modal interface provides the following controls:

Configure:

• Name — internal admin label.
• Slug — URL-safe identifier for shortcodes and code references.
• Product Query — combine zero or more filtering conditions:
  • Meta Query rules (post meta key + comparison operator + value).
  • Taxonomy Query rules (taxonomy + term IDs/slugs).
  • Post IDs (comma-separated) for explicit manual curation.
  Use Preview to inspect matching product counts before saving.
• Sort products — default sort order per listing (date, price, price-desc, sale, and popularity when enabled). Shoppers can override this via the storefront dropdown or ?orderby= parameters. See Sorting.
• Status — Active or Inactive.
• Context-sensitive — when enabled, the listing narrows down further based on the archive context of the hosting page (category or tag). Leave disabled if the listing should display an identical product set everywhere.

Shortcode for listing ID 42:

[instant_archive listing_id="42"]

The shorthand aliases listing="42" and id="42" are also supported.

Example: in-stock only collection

Display only products currently in stock — eliminating backorder or “notify me” rows from the layout.

1. Click “Add Listing” → Name: In Stock Only.
2. Under Meta Query, add a condition: key _stock_status, compare =, value instock.
3. Click Preview to verify matching product numbers.
4. Save and embed the shortcode on your “Available Now” landing page:

[instant_archive listing_id="42"]

Variation explosion rules remain fully applicable, allowing partially stocked variable products to present only in-stock variants as individual cards.

Workflow

1. Configure the filters you want displayed on the Filters tab.
2. Create a listing and define your query criteria.
3. Run Update Filters if you added or adjusted filter definitions.
4. Embed the shortcode on any WordPress page or page builder block.

Listing caps depend on your license level — see License.

Card loops

A card loop renders a standalone product grid that reuses your layout card designs without a filter sidebar and without client-side JavaScript hydration. The loop outputs pure, fast server-side HTML (SSR). It is ideal for homepage featured showcases, promotional campaigns, bestsellers, related products on single product pages, or curated category spotlights.

Where to find it

In WordPress, navigate to InstantFilter → Card loops. Here you will find an overview of all configured loops alongside their associated layout, query source, and shortcode with a one-click copy button.

Requirement: A product card design lives inside a layout (under schema.card_template). Ensure you have created or imported at least one layout under InstantFilter → Layouts before creating a card loop. Without an active layout, the “Add card loop” button remains locked.

Creating & configuring a card loop

Click “Add card loop” to open the configuration modal:

Available query sources (Product Query)

Context sensitivity & related products

When the “Respect WordPress context” option is enabled, the loop intelligently adapts to the viewing environment:

• On a single product page: Automatically retrieves products from the same categories as the currently viewed item, while excluding the current product itself — perfect for “Related products” or “You may also like” sections.
• On a category archive: Constrains results strictly to items within that category that also meet the query criteria (e.g. featured products within Sneakers).
• On standard pages (e.g. homepage): Applies no contextual restrictions; renders the configured query globally.

Shortcode & column controls

The standard shortcode for an admin-saved loop is:

[instant_cards id="3"]

You can override any setting from the saved loop directly via shortcode attributes:

[instant_cards id="3" limit="8" orderby="price" order="ASC" columns="4,2,1"]

Or define an entire loop inline without saving an admin configuration first:

[instant_cards card="layout:default-archive" source="featured" limit="4" columns="4,2,1"]

Columns & responsive layout

Without an explicit columns attribute, the loop uses smart default breakpoints:

• Desktop: renders items in a single balanced row up to 6 columns. From the 7th item onward, wraps into subsequent 6-column rows.
• Tablet (up to 1024px): renders up to 2 columns per row.
• Mobile (up to 600px): renders 1 full-width card per row.

Using columns="4,2,1" enforces 4 columns on desktop, 2 on tablet, and 1 on mobile. The CSS variable --ifcl-gap governs grid spacing (defaults to 1.5rem). The outer container carries class .ifcl-wrap, the grid carries .ifcl-grid, and individual items use the standard .ifc-card markup.

Layouts & StyleBuilder

InstantFilter decouples product card design completely from your WordPress theme. Rather than overriding rigid WooCommerce loop PHP templates, manage all your card presentations under InstantFilter → Layouts. Choose from ready-made designs via Card templates in the Template Library (included on all tiers), or build bespoke card layouts down to the pixel using the visual StyleBuilder (available on Pro and Agency). To display standalone product grids on marketing pages without sidebar filters, explore Card loops.

Template Library (all tiers)

Under InstantFilter → Layouts (or during the onboarding wizard), click the Card templates button to select from four production-ready presets:

• Classic (Default) — The proven e-commerce layout: product image, category eyebrow, title, price, and direct add-to-cart button. Ideal for all-round stores.
• Catalog (Compact) — A condensed presentation engineered for rapid scanning and dense inventories. Perfect for B2B stores, spare parts catalogs, and wholesale.
• Showcase (Storefront) — An eye-catching design featuring prominent product imagery, high-contrast badges, and refined typography. Great for consumer brands.
• Lifestyle (Hero Card) — An editorial, spacious card that puts visual storytelling first. Optimal for fashion, footwear, interior design, and lookbooks.

Binding to the Universal Archive or custom listings

Once you activate a template, you control where it renders:

• Universal Archive (v1.4.0) — Assign a template as your universal layout. All native WooCommerce archives (main shop, category pages, and product tags) use this template automatically.
• Per custom listing — In custom listing settings (under InstantFilter → Listings), select a specific layout to deviate from your store default.
• Via shortcode or Bricks — Override card layouts on a per-page basis with the card="my-layout-slug" attribute:

[instant_archive card="catalog"]
[instant_archive listing_id="42" card="lifestyle"]

StyleBuilder (Pro & Agency)

Need custom fields, unique layout structures, or strict brand alignment? With a Pro or Agency license, launch the visual StyleBuilder (click Edit on an existing layout or choose Add Layout).

1. Adding & structuring blocks

In the visual DOM tree, drag or click elements to build your structure:

• Product image — includes secondary hover image switching and aspect ratio controls.
• Title & Eyebrow — dynamically bound to product titles, brand taxonomies, or primary categories.
• Price display — regular prices, sale prices, and price ranges for variable items.
• Rating — star ratings and review counts.
• Badges — automatic badges for discounts, new arrivals, or stock alerts.
• Attributes & Color swatches — display size selectors or interactive color swatches directly on the card.
• Add to cart button — direct AJAX add-to-cart with loading state transitions.

2. Visual Design tab

Style every visual property without touching CSS through intuitive accordion controls:

• Spacing & size — padding, margins, width, height, and min/max dimensions.
• Background & color — background fills, typography colors, and accent tints.
• Border & shadow — per-side border styles, individual corner radius controls, and shadow presets.
• Typography — font sizing, font weight, line height, and text alignments.
• Layout & position — flexbox alignment, gap spacing, and absolute positioning (ideal for badges).
• Interactive states — distinct visual treatments for hover, active, and checked states.
• Custom CSS & classes — assign custom CSS classes or custom animation utility classes.

3. Responsive design cascade (Wide → Mobile)

Styling properties follow a predictable top-down cascade:

Wide (1920px+) acts as the master style. Settings defined here automatically cascade down to Desktop, Tablet, and Mobile. Entering values on smaller breakpoints creates targeted overrides, keeping your styling maintainable across devices.

4. Safe drafts & publishing workflow

All work in the StyleBuilder autosaves to an isolated draft (draft). Shoppers on your live store continue viewing the published design until you click Update / Publish. To discard recent adjustments, click Discard to revert to the live version immediately.

Need StyleBuilder access? Explore plans on our pricing page.

Hooks & integrations

InstantFilter offers flexible extension points for inserting custom elements into the product grid or individual cards. The first two approaches are code-level hooks for developers, while the wishlist integration is an out-of-the-box block in the StyleBuilder.

Between cards

The instantfilter_between_cards action allows you to inject custom grid cells between product cards. You have full control over the injected content: promotional banners, editorial notices, shortcodes, calls-to-action, or ad units. This hook executes during server-side rendering once per product slot, immediately before the card at that index — including vacant slots on the final page.

do_action( 'instantfilter_between_cards', int $index, int $per_page );

• $index — the zero-based product slot before which your cell is placed (e.g. 0 injects before the first product, 4 injects before the fifth).
• $per_page — the configured product count per page. Injected cells do not increment this product quota.

A cell is only injected if your callback explicitly echoes markup. If nothing is output, no blank DOM container is generated. InstantFilter automatically wraps your content in <div class="if-grid-insert">. Output only inner markup, and avoid adding the ifc-card class (reserved exclusively for product cards).

During client-side filtering, sorting, and pagination, the insert remains pinned at its assigned slot without re-rendering. If an active filter produces fewer products than the insert position, InstantFilter hides the cell; it automatically reappears whenever a result set fills the grid up to that slot.

Injecting a single banner before the fifth product (index 4):

add_action( 'instantfilter_between_cards', function ( int $index, int $per_page ): void {
    if ( $index !== 4 ) {
        return;
    }
    echo '<a class="my-insert" href="/spring-sale">Spring Sale — Up to 40% Off</a>';
}, 10, 2 );

Injecting a recurring help banner every 9 products (before positions 9, 18, 27, etc.):

add_action( 'instantfilter_between_cards', function ( int $index, int $per_page ): void {
    if ( $index === 0 || $index % 9 !== 0 ) {
        return;
    }
    echo '<aside class="my-insert"><h3>Need assistance?</h3><p>Contact our specialists.</p></aside>';
}, 10, 2 );

Retrieving dynamic banner data from Advanced Custom Fields (ACF) option pages:

add_action( 'instantfilter_between_cards', function ( int $index, int $per_page ): void {
    if ( $index !== 4 ) {
        return;
    }
    $image = get_field( 'grid_banner_image', 'option' );
    $url   = get_field( 'grid_banner_link', 'option' );
    if ( ! $image || ! $url ) {
        return;
    }
    printf(
        '<a class="my-insert" href="%s"><img src="%s" alt="Promotion"></a>',
        esc_url( $url ),
        esc_url( $image['url'] )
    );
}, 10, 2 );

Sidebar hooks

The filter sidebar exposes three dedicated actions for custom content and promotional messaging:

• instantfilter_sidebar_before_facets — executes directly below the sidebar header, before the first filter.
• instantfilter_between_facets — executes between individual filter blocks.
• instantfilter_sidebar_before_apply — executes immediately above the “Show products” button in the mobile off-canvas drawer.

Callbacks that output no markup leave no empty DOM wrappers. For example, add a trust badge above your filter facets:

add_action( 'instantfilter_sidebar_before_facets', function (): void {
    echo '<div class="my-sidebar-badge">Free shipping & 30-day returns</div>';
} );

Or place an interactive support link above the mobile drawer confirmation button:

add_action( 'instantfilter_sidebar_before_apply', function (): void {
    echo '<p class="my-drawer-help">Need help choosing? <a href="/contact">Chat with us</a></p>';
} );

Custom slot

A Custom Slot is a drag-and-drop block within the StyleBuilder. Place it anywhere on your card layout where dynamic third-party markup or shortcodes should render. InstantFilter invokes the instantfilter_card_slot_html filter and renders the returned HTML into that card position.

The filter callback receives the slot identifier. The default name is custom_slot_1. If you specify a distinct name in the builder, match it in your callback to render different content across multiple slots on a single card:

add_filter( 'instantfilter_card_slot_html', function ( $html, $slot_name, $product, $node ) {
    if ( 'custom_slot_1' !== $slot_name ) {
        return $html;
    }

    return do_shortcode( '[your_custom_badge_shortcode]' );
}, 10, 4 );

During hook execution, global $product is set to the current WooCommerce product instance. Any shortcodes or functions querying the global product context resolve correctly.

• $product['id'] references the specific variation ID if the card represents an exploded variation. Wishlist plugins storing this ID will target the exact variation rather than the parent.
• $product['product_id'] and $product['parent_id'] always point back to the main parent product.

On initial page load, PHP renders the slot via SSR. During subsequent client-side filtering, the pre-compiled HTML is extracted from the export payload and hydrated instantly alongside titles and prices.

Wishlist integration

The StyleBuilder includes a dedicated Wishlist block. In the pre-built library layouts (Classic, Catalog, Showcase, and Lifestyle), the heart icon is positioned in the upper right corner on a clean badge.

InstantFilter automatically detects and connects to installed wishlist plugins in this priority order:

1. YITH WooCommerce Wishlist
2. TI WooCommerce Wishlist
3. WPC Smart Wishlist
4. WCBoost Wishlist

Within the block settings, you can retain automatic detection or explicitly bind to one of the four supported plugins. If none of these plugins are active, no button is rendered.

Products already saved to a shopper’s wishlist display an active filled heart on initial page load. This state is preserved seamlessly throughout client-side filtering, sorting, and pagination.

For variable products:

• Cards representing a fully exploded variation save that specific variation ID.
• Cards representing partial variations (such as color only, where size remains unselected) save the parent product ID, as third-party wishlist plugins do not support incomplete attribute combinations.

ItemList SEO schema

The initial server-rendered HTML (SSR) of shop and category pages automatically embeds a structured JSON-LD ItemList schema for search engine indexers. This schema provides Google and Bing with precise product positions and canonical URLs.

You can fine-tune or disable this schema using two WordPress filters:

// Completely disable the archive ItemList schema:
add_filter( 'instantfilter_archive_itemlist_enabled', '__return_false' );

// Programmatically modify the ItemList schema payload:
add_filter( 'instantfilter_archive_schema', function ( array $schema ): array {
    $schema['name'] = 'Featured Collection';
    return $schema;
} );

Fixed card DOM skeleton (Architecture)

InstantFilter maintains strict separation between DOM structure and dynamic data:

• PHP generates the skeleton once: Grid markup (#if-products) and every product card (.ifc-card) are written during server-side rendering. All target nodes (images, titles, badges, pricing, custom slots) exist in the initial DOM tree.
• JavaScript mutates data in place: During client-side filtering, the grid is never demolished or rebuilt via innerHTML. The lightweight JS engine simply binds to existing DOM nodes and updates text, image sources, hyperlinks, and status classes.
• Zero Cumulative Layout Shift (CLS): Card elements without active data receive the is-if-empty class (display: none), and vacant slots on shorter pages are marked is-if-vacant. The browsing experience remains instantaneous, stable, and completely flicker-free.

Settings

InstantFilter → Settings — global configurations for indexing, export generation, sidebar behavior, and display defaults. Changes configured here apply across all listings unless overridden per shortcode.

Index & export

Performance (batch sizes)

• Items Batch Size — number of products processed per batch during “Reload Products” (default: 200).
• Filters batch size — number of products processed per batch during “Update Filters” (default: 50, usually smaller than items).
• Filter repeater batch size — catalog scan chunk size when generating repeater filters (default: 50).

Lower batch thresholds if your hosting server encounters execution timeouts; increase them on dedicated hosting for faster complete re-indexes.

Sidebar behavior

• Max expanded filters — number of facets displayed fully open on initial render; additional filters collapse accordion-style (applies across all filter types: checkboxes, radio buttons, color swatches, range sliders, dropdowns, ratings, and toggles; 0 = all collapsed).
• Max Values Per Filter — number of facet options rendered server-side before the “More…” expansion toggle appears (default: 20; 0 = render all options). For hierarchical taxonomies, only top-level terms count toward this limit to keep sub-groups intact.
• Max sidebar filters — caps the total number of filters rendered in the sidebar (including repeater filters; default: 25; 0 = unlimited). Prevents excessive DOM nodes and sluggish SSR on shops with large attribute sets.

Card display labels

• Variable Product Price Display — configure From $… versus a full price range ($10 – $30) for parent products.
• Sale Price Display — show original strikethrough price + sale price, or sale price only.
• Hidden Price Placeholder — fallback text when a product conceals pricing in WooCommerce.
• Stock status labels — customize public labels for In stock, Out of stock, and On backorder.

Debug tools

Debug mode and Debug log (when present) activate verbose logging and expose the manual “Build Export” button in the admin header. Keep disabled in production environments unless troubleshooting an active issue.

The Exports admin tab is only visible when WordPress WP_DEBUG is active — intended for developer diagnostics rather than routine store configuration.

Sorting

InstantFilter sorts products in the catalog via a dedicated storefront sort dropdown. Shoppers can switch between options including newest, price, sale discount, and — when enabled — Most popular.

Sort by popularity

Most popular orders products by WooCommerce sales volume (total_sales on the parent product). It reflects verified purchases rather than page views or review scores. Product variations inherit the sales tally of their parent product.

Enabling popularity sorting

1. Navigate to InstantFilter → Settings → the Index & export section.
2. Check Enable popularity sorting and save changes.
3. Rebuild export files (handled automatically upon indexing if Auto Build Exports is active, otherwise triggered via the admin export action).

Once enabled, Most popular becomes the global default sort across archives and custom listings, unless overridden by a listing setting, shortcode attribute, or URL query parameter (see hierarchy below).

On large catalogs exceeding 15,000 published products, the settings panel displays a notice regarding memory overhead in the export snapshot. The feature remains fully operational and is not blocked.

Default sort per listing

Under the Listings tab, you can assign an explicit default order per listing using the Sort products setting. The Most popular option is only available when the global feature is toggled on.

Supported sort keys across admin and storefront:

• date — newest items first
• price — lowest price first
• price-desc — highest price first
• sale — steepest discounts first
• popularity — highest sales volume first (only when enabled)

Sort precedence (which sort takes priority?)

From highest priority to fallback default:

1. URL parameter — ?orderby=popularity (also accepts price, price-desc, sale, date, title; legacy WooCommerce syntax: ?orderby=price&order=desc)
2. Shortcode attribute — orderby="..." or sort="..." on [instant_archive] or [instant_cards]
3. Listing default — default_sort configured on the listing in admin
4. Global default — popularity when enabled, otherwise date

Shoppers can change the active sorting using the storefront dropdown at any time. Their selection is automatically mirrored in the browser URL.

Sorting via shortcode & URL

You can set the initial sort order directly on the shortcode using the orderby attribute (or alias sort):

[instant_archive orderby="price"]
[instant_archive listing_id="42" orderby="popularity"]

Listing with a dedicated default sort

In the admin listing modal, set Sort products to Most popular and place:

[instant_archive listing_id="42"]

Every visitor to that page starts sorted by popularity, unless they interact with the dropdown or visit via a parameterized URL.

Landing pages with fixed sort URLs

Link directly to curated campaign pages with an explicit sort order via query strings:

https://yourshop.com/best-sellers/?orderby=popularity
https://yourshop.com/sale/?orderby=sale
https://yourshop.com/shop/?orderby=price-desc

Works seamlessly on any page embedding [instant_archive] (or the Universal Archive) — no dedicated custom listing required.

Sort order of filter values (WooCommerce drag & drop)

Beyond sorting products, you can customize the ordering of facet options within the sidebar. For attribute-based filters, select “WordPress order (drag-and-drop)” under Filters → Sort order in the filter edit modal. InstantFilter will respect the custom term ordering configured directly within WooCommerce (Products → Attributes → Configure terms). This guarantees that sizes (e.g. XS, S, M, L, XL) or custom swatches display in logical progression rather than strictly alphabetical order.

Combining listings and URLs

[instant_archive listing_id="42" per_page="36"]

On /brand/nike/?orderby=date, the URL parameter overrides the listing default. This is ideal for promotional campaigns that need to present fresh arrivals while the standard store listing defaults to bestsellers.

When do sales rankings update?

Sales metrics are not recomputed live on each pageview. They are captured when compiling the export payload. Following peak sales events or promotions, simply rebuild the export to refresh storefront rankings. Full re-indexing is unnecessary for sales updates — a standard export rebuild suffices.

Products with zero recorded sales are assigned a value of 0 and appear at the end of results. In the event of tied sales figures, the newer product takes precedence.

Troubleshooting

• No change after enabling — Did you rebuild the export? Without an export rebuild, sales metrics remain absent and products default to zero sales.
• Unexpected rankings / all items appear equally popular — Verify total_sales values in WooCommerce (corrupted negative numbers like -1 can disrupt ordering calculations).
• Most popular missing from dropdown — The global setting is disabled, or exports have not been rebuilt since activating the feature.
• Shortcode sorting behaves unexpectedly — Review URL query parameters (?orderby=), listing defaults, and global defaults in that priority order.

See also Settings, Listings, and Shortcodes.

Shortcodes

InstantFilter provides five versatile shortcodes. All require an active license and a completed index.

instant_archive

The complete storefront experience: interactive filters, reactive product grid, toolbar, and pagination. This is the most common integration point.

[instant_archive]
[instant_archive listing_id="42"]
[instant_archive card="my-layout" per_page="24" show_filter_bar="false"]

Context-sensitive on native WooCommerce archives. Without an explicit listing_id, this shortcode renders the Universal Archive. On native WooCommerce archives (shop, product categories, tags), it automatically scopes products and facet options to the current page — the exact same shortcode yields different products on /shop/, /product-category/sneakers/, and /product-tag/sale/.

On custom WordPress pages (landing pages, builder layouts, blog posts), native archive globals do not exist. In these cases, the Universal Archive defaults to your full catalog. To target a specific product subset on a custom page, create a custom listing on the Listings tab and provide its ID:

[instant_archive listing_id="42"]

instant_cards

Renders a standalone product loop (featured, sales, bestsellers, related items) based on your card designs, without a filter sidebar and without client-side JavaScript overhead. Renders as pure server-side HTML. See Card loops for full documentation.

[instant_cards id="3"]
[instant_cards id="3" limit="8" orderby="price" order="ASC" columns="4,2,1"]
[instant_cards card="layout:default-archive" source="featured" limit="4"]

instant_filter

Renders a single standalone filter widget outside the default sidebar structure.

[instant_filter prop="pa_color"]

Use the filter key (prop) from the Filter Definitions table on the Filters tab (also copyable via row actions in admin).

instant_filters

Renders the complete filter sidebar only — ideal for custom split layouts.

[instant_filters]
[instant_filters group="my-group"]

instant_all

Renders all available filters adapted to current context.

[instant_all]
[instant_all style="interface"]

style: sidebar (default) or interface.

Bricks Builder Integration

InstantFilter provides a comprehensive native Bricks Builder integration. When the Bricks theme is active, InstantFilter detects it automatically and registers four custom elements under the InstantFilter category in the Bricks elements panel.

You never need to copy-paste shortcodes or insert raw HTML blocks: drag elements straight onto your canvas or archive templates with full live preview inside the Bricks builder.

The 4 Bricks Elements

Controls in Bricks

When selecting an InstantFilter element in Bricks, configure content options directly in the left settings panel:

• Listing — Select which product collection to render. Choose Universal for automatic WooCommerce context, or select a custom listing defined in InstantFilter → Listings.
• Products per page (per_page) — Define how many products display per page (default: 24).
• Show filter bar (show_filter_bar) — Toggle the toolbar above the grid (disabling moves active filter chips into the sidebar automatically).
• Card design — Leave set to Auto to inherit your universal template or listing default, or explicitly choose a template from the Template Library or StyleBuilder.
• Filter group (IF Filter sidebar) — Optional: enter a group slug to render only filters belonging to that group.
• Filter (IF Single filter) — Pick from a searchable dropdown of all configured filters (e.g., pa_color, pa_size, or price).

Using Bricks WooCommerce Archive Templates

Building your shop or category archives using Bricks Templates (type Product Archive)?

1. Open your Product Archive template in Bricks Builder.
2. Add a container and insert the IF — Sidebar + Grid element (or place separate IF — Filter sidebar and IF — Grid elements).
3. Keep the Listing set to Universal. InstantFilter detects whether the visitor is viewing /shop/, a specific product category, or a product tag, and automatically scopes products, filter counts, and facets accordingly.
4. Configure template conditions in Bricks (e.g., Entire website WooCommerce product archives).

Styling: Bricks vs. InstantFilter

To ensure filtering speeds consistently remain under 5 milliseconds, styling responsibilities are clearly divided:

• Bricks Style tab: Use standard Bricks controls (Margin, Padding, Background, Container widths) to embed the outer archive container into your overall page layout.
• InstantFilter Layouts & StyleBuilder: Product card layouts, facet typography, swatches, badges, and mobile drawer styles are managed centrally in InstantFilter. These compile into ultra-fast, pre-hydrated client-side templates.

Troubleshooting

No products in the grid

• Run Reload Products — status pill should not display “No products loaded”.
• Confirm WooCommerce products are published and fall within your active license product limit.
• For custom listings, verify the query returns valid IDs (check the Items column on the Listings tab).

Filters empty or counts show zero

• Run Update Filters after creating or enabling filters.
• Ensure the filter Reference matches real catalog data (e.g. attribute terms are assigned to published products).
• Filter repeater: wait for the catalog scan to finish; ensure relevant attributes are not in the excluded attributes list.

Filters work in admin preview but not on the site

• Confirm Auto Build Exports is enabled, or rebuild export files manually in debug mode.
• Purge page caches (WP Rocket, LiteSpeed, Redis, Cloudflare, etc.) after re-indexing.
• Verify the shortcode is added to the public page — not just tested in the admin listing preview.

Filter clicks reload the page or feel sluggish

• Open DevTools → Network: after initial page load, filter clicks must not trigger server-side admin-ajax requests. All filtering runs client-side.
• If exports fail to load, inspect the browser console for 404 or decompression errors on export assets.
• Ensure caching plugins do not aggressively block or rewrite JSON / gzip files located in /wp-content/uploads/instantfilter/.

Variation cards wrong or missing

• Re-run Reload Products after changing variation explosion rules.
• explode_unique intentionally omits variations without a dedicated image — this is expected behavior.
• Check both the Variations tab and individual filter Advanced Settings for conflicting explosion rules.

License / limit errors

• Re-activate your license key on the License tab; deactivate it first before migrating to a new domain.
• “Limit Reached” warnings indicate product, listing, or domain quotas — upgrade via pricing.

Still stuck?

See our FAQ for trial details, billing, and refund terms. For implementation assistance, email tom@instantstack.co with your listing ID, shortcode URL, and a screenshot of your admin status pill.

For custom development, see the Hooks & integrations section for banner injection, sidebar hooks, custom card slots, and wishlist integration.