InstantFilter documentation

Quick start

InstantFilter runs inside WooCommerce. You configure filters in WP Admin → InstantFilter, index your catalog, then place a shortcode on a shop or landing page.

1. Start your trial and install

1. Start a 14-day trial on our pricing page. Add your card at checkout — you are only charged when the trial ends.
2. Download the plugin zip from your Lemon Squeezy confirmation email.
3. In WordPress: Plugins → Add New → Upload Plugin, activate InstantFilter.
4. Open InstantFilter → License and paste your license key. Other tabs stay locked until the key validates.

2. Reload Products

Click Reload Products in the admin header. This populates the wp_if_items table with your WooCommerce catalog. After this first run InstantFilter keeps the table in sync automatically when you save, update or delete products — you only need to reload manually after large imports or if you spot drift between WooCommerce and the Items count.

3. Add filters

Go to the Properties tab and click Add Filter. The dialog covers source, reference, label and display type:

• Source — where the data lives (taxonomy, attribute, meta, ACF, or a Loop source that creates filters for every attribute at once).
• Reference — the specific field or attribute (e.g. pa_color, product_cat).
• Filter Name — what shoppers see in the sidebar.
• Display Type — checkbox, color swatch, range slider, dropdown…

Save and repeat for every filter you want in the sidebar. See Properties for the full field reference.

4. Update Filters

Click Update Filters in the admin header. InstantFilter indexes every enabled property against your catalog and (with Auto Build Exports on, the default) builds the JSON export so the frontend can filter client-side.

5. Place a shortcode

Add this to a page, category template, or page builder block:

[instant_archive]

That renders the full archive: filter sidebar, product grid, sort bar and pagination. The first page load is server-rendered for SEO; after the export hydrates, filter clicks resolve in the browser.

Continue with Properties for filter setup, Listings for custom collections, and Shortcodes for placement options.

How indexing works

InstantFilter separates what products exist from what shoppers can filter on and what the browser loads. Three layers, each with its own admin action:

Delta sync — you rarely re-run Reload Products

Once Reload Products has run for the first time, InstantFilter keeps the items table in sync through WordPress hooks. Saving, updating, trashing or restoring a product fires a delta update that touches only the affected rows — no full rebuild.

Run Reload Products manually when:

• You imported a large batch of products outside the normal save flow (CSV, WP All Import, REST API bulk).
• You see a mismatch between the WooCommerce product count and the InstantFilter Items count.
• You changed variation explode rules and want to confirm everything is in line.

For everyday catalog edits, the delta keeps the index current without you doing anything.

Header status indicator

The pill next to the action buttons reflects the current state:

• No products loaded — first run; click Reload Products.
• X of Y filters active — some properties need re-indexing; click Update Filters.
• X filters active — ready for the frontend.
• No filters created — add at least one filter on the Properties tab.

When to run Update Filters

• After adding, editing, disabling or reordering filters.
• After generating Loop properties (it scans your catalog for every attribute).
• After changing variation explode rules so option counts reflect the new card structure.

The export rebuilds automatically when Auto Build Exports is on (recommended). The manual Build Export button only appears when WordPress debug mode is enabled.

First paint vs client-side filtering

Shoppers see a full HTML product grid on the first request (SSR) so search engines and screen readers get the same content. The export loads in the background; once hydrated, filter and pagination clicks do not hit your server for filter resolution. That is why items, properties and export must all be current before you judge performance on staging.

License

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

Activate your key

1. Paste the license key from your Lemon Squeezy purchase or trial email.
2. Click activate. The plugin validates against InstantStack servers and unlocks Properties, Variations, Listings, Cards and Settings.
3. Without a valid license, only the License tab is usable — other tabs are greyed out.

Trial flow

Trials are issued through Lemon Squeezy (14 days on the website; the plugin may show a longer trial window depending on license server response). After checkout you receive a download link and license key by email.

What your tier controls

Site limits from Founders pricing. If you exceed a product or listing limit, indexing buttons show Limit Reached until you upgrade.

Deactivate or move sites

Use the deactivate control on the License tab before migrating to another domain, then activate again on the new site. For billing or refund questions see the FAQ.

Properties (Filter Definitions)

InstantFilter → Properties is where you define which filters appear in the sidebar. Each row is one filter. Enabled filters are indexed when you click Update Filters.

Properties table

• Active — toggle includes or excludes a filter from indexing and the frontend.
• Filter Name — label shoppers see in the sidebar.
• Source — where data comes from (General, Taxonomy, Attribute, Loop, etc.).
• Type — display type (checkbox, range, color swatch, …).
• Actions — edit, delete, copy shortcode [instant_filter prop="…"].

Drag rows to reorder filters. Loop-generated attributes appear nested under their loop parent.

Loop properties

Instead of creating one filter per attribute by hand, use a loop source:

• Loop Global Attributes — scans the catalog and creates a child filter for each global attribute (pa_*).
• Loop Custom Attributes — same for custom product attributes.

When you save a loop property, the plugin generates many child filters automatically. Re-run Update Filters after generation. Use Exclude Attributes (one key per line) to skip attributes you do not want in the sidebar.

Result on the storefront: each included attribute becomes its own filter block in the sidebar, sorted per your drag order.

Add Filter dialog — field reference

Click Add Filter to open the modal. Key fields:

See also Variations for catalog-wide explode rules and Settings for sidebar limits.

Variations

Variable products are WooCommerce’s way of selling one parent product in multiple flavours — sizes, colors, finishes. By default the storefront shows the parent as a single card with a price range. Exploding a variation attribute splits that one card into multiple cards, one per variation. This is the difference between “Nike Air Force 1” as a single tile or three tiles for black, white and blue.

Visual example

One variable product with three color variations. Top row is the default parent display; bottom row is the same product with color exploded:

Display modes

Where you configure it

Two places — both write to the same central explode rule list:

1. Properties → Add/Edit Filter → Advanced Settings. When the filter source is an attribute (e.g. pa_color), the modal shows a Variation Display Mode field. Use this when you both want the attribute as a sidebar filter and control how it explodes variations.
2. Variations tab → Add attribute. Use this when you want to explode an attribute without exposing it as a filter in the sidebar. Example: split products into individual cards by color, but never let shoppers click a color filter.

An attribute managed via a property shows a Via property badge on the Variations tab and stays in sync when you edit the filter. Manual entries are edited on the Variations tab only.

Sub-parents on partial explode

Shoes often have two attributes: color and size. If you explode on color but not on size, InstantFilter creates one card per color — a sub-parent that groups every size for that color:

• Red — sizes 1, 2, 3
• Blue — sizes 1, 2, 3
• etc.

These sub-parents are not WooCommerce variations. They only exist in InstantFilter’s index so the grid can show one tile per exploded attribute. In WooCommerce the real variations are still the individual combinations:

• Red, size 1
• Red, size 2
• Red, size 3

Each of those has its own variation record in WooCommerce — including its own image field. The sub-parent card has no image in Woo; InstantFilter picks one from the underlying variations when it renders the tile. Which image you see depends on what you uploaded on those variation rows.

What to do in WooCommerce: set the variation image on every row, and choose a photo that highlights the attribute you exploded on — not the one you left grouped. For color explode + size grouped, every red variation gets a photo of the red shoe, regardless of size:

• Red, size 1 → red shoe (not a size-specific shot)
• Red, size 2 → red shoe
• Red, size 3 → red shoe

Same idea for blue, green, and so on. If size-1 and size-2 of the same color use different photos, the sub-parent may show whichever variation InstantFilter resolves first — so keep them consistent on the attribute you care about.

Result on the storefront: the product grid shows parent cards, sub-parents, or individual variation cards depending on your rules; filter counts reflect the exploded items, not just parent SKUs.

Listings

A listing is a product collection with its own shortcode and (optionally) its own filter set. Use listings when one shop page is not enough — sale landing pages, brand shops, in-stock-only views, or B2B subsets.

Universal Archive (system listing, ID -1)

Every install includes a built-in listing that mirrors the WooCommerce archive context. Drop its shortcode on a Woo archive page and it knows where it lives:

• On the main shop — all indexed products and the full filter set.
• On a category archive — only products in that category, with filters and counts adapted to the context.
• On a tag archive — same, scoped to the tag term.

Shortcode: [instant_archive]

Custom listings

Click Add Listing on the Listings tab. The dialog mirrors the screenshot below:

Configure:

• Name — admin label.
• Slug — URL-safe identifier used internally.
• Product Query — combine zero or more of:
  • Meta Query conditions (post meta key + compare + value).
  • Taxonomy Query conditions (taxonomy + term IDs/slugs).
  • Post IDs (comma-separated) for explicit picks.
  Use Preview to see how many products match before saving.
• Sort products — default sort order; visitors can override via the storefront sort dropdown.
• Status — Active or Inactive.
• Context-sensitive — when enabled the listing additionally respects the WordPress archive context (category, tag) the page sits on. Leave off when you want the listing to render the same products regardless of where the shortcode is placed.

Shortcode for listing ID 42:

[instant_archive listing_id="42"]

The aliases listing="42" and id="42" also work.

Example: in-stock only listing

Show only products that are currently in stock — no “notify me” or backorder rows in the grid.

1. Add Listing → Name: In stock.
2. Under Meta Query, add a condition: key _stock_status, compare =, value instock.
3. Click Preview to confirm the product count looks right.
4. Save and place the shortcode on your “Available now” page:

[instant_archive listing_id="42"]

Variation explode rules still apply, so a partially out-of-stock variable product can show only its in-stock variations as cards.

Workflow

1. Create the filters you want available on the Properties tab.
2. Create a listing and configure the query.
3. Run Update Filters if you changed properties.
4. Paste the shortcode on a WordPress page or page-builder block.

Listing limits depend on your license tier — see License.

Card Builder

InstantFilter → Cards (Pro and Agency) replaces the default product card template with a visual layout you design in the Card Builder.

When to use it

• You need custom card HTML/CSS without editing theme templates.
• Different listings should show different card layouts.
• You want badges, swatches, or extra fields bound to product data.

Basic tier uses the built-in PHP card template — no Card Builder access.

Creating a card

1. Open the Cards tab and click to create or edit a card.
2. The builder opens full-screen (admin.php?page=if-cards-builder).
3. Design the layout, bind fields (title, price, image, attributes, etc.), save.
4. Note the card slug shown in the list.
5. Re-index after every publish. Click Update Filters so the data your card binds to is written into the property tables and picked up by the export. Without this step bound fields can read stale or missing values on the frontend.

Assign to a listing or shortcode

[instant_archive card="your-card-slug"]
[instant_archive listing_id="42" card="your-card-slug"]

Resolution order: explicit card attribute → listing default in options → first active site card → legacy template fallback.

Theme overrides (advanced)

You can still override PHP templates in your theme under instantfilter/ if you prefer code to the builder. The builder is the supported path for agencies who want a UI.

Upgrade on the pricing page if Card Builder is locked.

Settings

InstantFilter → Settings — global indexer, export, sidebar and display defaults. Changes here affect every listing unless overridden per shortcode.

Index & export

Performance (batch sizes)

• Items Batch Size — products per batch during Reload Products (default 200).
• Properties Batch Size — products per batch during Update Filters (default 50, usually lower than items).
• Loop Generation Batch Size — catalog scan chunk size when generating loop properties (default 50).

Lower batches if your host times out; raise them on dedicated servers for faster full re-indexes.

Sidebar behavior

• Max Expanded Properties — how many filters start fully open; rest collapse accordion-style (0 = all collapsed).
• Max Sidebar Properties — cap total filters rendered (default 25, 0 = unlimited). Prevents huge DOM on shops with dozens of loop children.

Card display labels

• Variable Product Price Display — From vs Range for parent variable products.
• Sale Price Display — show strikethrough + sale price, or sale price only.
• Hidden Price Placeholder — text when a product hides price in WooCommerce.
• Stock status labels — customize In stock / Out of stock / On backorder strings on cards.

Debug

Debug mode and Debug log (when present) enable verbose logging and the manual Build Export header button. Turn off on production unless you are diagnosing an issue.

The Exports admin tab only appears when WordPress WP_DEBUG is enabled — it is for developer inspection, not day-to-day setup.

Shortcodes

InstantFilter registers four shortcodes. All require a valid license and completed indexing.

instant_archive

Full shop experience: filters + product grid + pagination. Most common entry point.

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

Context-sensitive on Woo archives. Without a listing_id, this shortcode renders the Universal Archive listing. On a real WooCommerce archive page (shop, product category, product tag) the listing automatically scopes filters and products to the page you are on — the same shortcode shows different inventory on /shop/, /product-category/sneakers/ and /product-tag/sale/.

On a custom WordPress page (any non-archive URL: landing page, builder template, content page) there is no archive context to detect. The Universal Archive falls back to all products. To scope a custom page, build a custom listing on the Listings tab and pass its ID:

[instant_archive listing_id="42"]

instant_filter

Render a single filter outside the default sidebar layout.

[instant_filter prop="pa_color"]

Use the property key from the Properties table (also copyable from the admin row actions).

instant_filters

Filter sidebar only — embed filters elsewhere in the page layout.

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

instant_all

All available filters for the current context.

[instant_all]
[instant_all style="interface"]

style: sidebar (default) or interface.

Troubleshooting

No products in the grid

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

Filters empty or counts show zero

• Run Update Filters after creating or enabling properties.
• Ensure the property Reference matches real product data (e.g. attribute has values on products).
• Loop properties: wait for generation to finish; check excluded attributes list.

Filters work in admin preview but not on the site

• Confirm Auto Build Exports is on, or rebuild export in debug mode.
• Purge page cache (WP Rocket, LiteSpeed, etc.) after indexing.
• Verify the shortcode is on the page you are testing — not only in the admin listing preview.

Filter clicks reload the page or feel slow

• Open DevTools → Network: after first interaction, filter clicks should not trigger new admin-ajax filter calls.
• If the export failed to load, check browser console for 404 on export files.
• Try Export Strategy → Auto in Settings before switching to FX or inverted manually.

Variation cards wrong or missing

• Re-run Reload Products after explode rule changes.
• explode_unique hides variations without their own image — expected behavior.
• Check both Variations tab and property Advanced Settings for conflicting explode rules.

License / limit errors

• Re-activate key on License tab; deactivate before moving domains.
• Limit Reached on buttons means product, listing, or site cap — upgrade via pricing.

Still stuck?

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

Developer hooks and deep architecture guides are planned for the Guides section — not linked here until those pages exist.