Products Search Box

Overview

A search input field that allows customers to search the product catalog. Searches against product titles and descriptions synced from BigCommerce and stored in WordPress® for fast, responsive search results.

Requirements

• Parent block: Must be inside commerce-connect/products
• BigCommerce data: Product catalog with searchable title and description fields

Configuration

Attributes

None. This block has no configurable attributes.

Block Support

• HTML editing: Not supported
• Multiple instances: Supported (can have multiple search boxes)
• Alignment: Supported

Usage

Placement

This block must be placed inside the Products block. It cannot be used outside of this context. Typically placed at the top of product listing pages or in the site header.

Common Patterns

From the demo video script, the search box enables product discovery:

[Products Block]
  → Products Search Box ← (Search input field)
    [Search input: "linen"]
    [Search button or auto-submit on enter]
  Products Filters
  Products Grid (filtered by search term)

When a customer searches:

1. Types search term (e.g., “linen”)
2. Hits Enter or clicks Search button
3. Products block queries WordPress® for matching products
4. Results display in the product grid
5. Available filters update based on search results

The demo shows: “WordPress® is searching the synced product catalog - the product information lives in WordPress® after being synced from BigCommerce. Fast search because the product data is stored in WordPress®.”

Technical Details

CSS Classes

The block uses standard block wrapper attributes.

Data Source

The Products Search Box submits search queries to the parent Products block. The Products block then:

• Searches WordPress® product post type (not BigCommerce API)
• Matches search term against product titles and descriptions
• Returns matching products with full metadata
• Updates available filters based on search results

Product data is synced from BigCommerce and stored in WordPress®, enabling fast search without API calls to BigCommerce on every query.

Search Parameters

When a search is submitted:

• Adds ?search= parameter to URL (or ?s= as fallback)
• Products block processes the search parameter
• Query runs against WordPress® product database
• Results display in the product grid

The search term persists in URL parameters, so:

• Customers can bookmark search results
• Filters can be applied on top of search results
• Pagination works correctly with search context
• Sorting preserves the search term

Troubleshooting

Search box not displaying

• Verify the block is inside a Products parent block
• Check that the block is added to the template/page
• Ensure JavaScript is loaded and executing

Search returns no results when products exist

The Products block displays “No results found for [search term]” when:

• Search query is present in URL
• No products match the search term

To troubleshoot:

• Verify product titles/descriptions contain the search term
• Check that product data is fully synced from BigCommerce
• Test in WordPress® admin to confirm products are published
• Try broader search terms (single words vs. phrases)

Search is slow

Search should be fast because:

• Products are stored in WordPress® (not queried from BigCommerce)
• WordPress® database handles the search query
• No external API calls required for search

If search is slow:

• Check WordPress® database performance
• Review server resources and query execution time
• Consider indexing product titles/descriptions for better search performance
• Check for WordPress® or plugin conflicts affecting search queries

Search not respecting category context

The search box searches ALL products by default, not just the current category. This is intentional for broader product discovery.

If you need category-scoped search:

• Customer can use both search and category filters together
• Available filters will update based on search results
• Customers can select category from filters to narrow search results

Special characters or quotes in search

• Ensure search input sanitizes special characters
• Test search with quotes, apostrophes, and other special characters
• Verify SQL query escaping is correct
• Check for encoding issues with non-ASCII characters

Search term not visible in search box after submit

After search submission, the search term should:

• Persist in URL as ?search= parameter
• Be re-populated in the search box input field

If search term doesn’t persist:

• Check that search parameter is in URL after submit
• Verify search box input reads from URL parameter
• Ensure page reload or AJAX update preserves search context