SwiftSearch for Algolia

3. Features & Capabilities

Full Technical Feature List

4. Displaying the Search

To display the clean search bar anywhere on your site (header, sidebar, or inside a page), use the shortcode:

[swift_search_algolia]

(The shortcode [swift_search] is also fully supported as a drop-in alias).

Advanced Options

You can customize the search behavior using specific attributes:

• placeholder: Custom placeholder text (Default: "Search...").
• limit: Maximum number of results to display (Default: 10).
• show_thumbnail: "true" to show images, "false" for text-only.
• post_types: Comma-separated list (e.g. "product,post").

Example Usage

[swift_search_algolia placeholder="Find products..." limit="8" post_types="product" show_price="true"]

5. Theming & Customization

The search interface is designed to inherit your theme's fonts, but you can override styles using standard CSS.

/* The Outer Wrapper */
.ss-wrapper { 
    max-width: 600px; 
}

/* The Search Input Box */
.ss-search-box input { 
    border-radius: 8px;
    border: 2px solid #e5e7eb;
}

/* Highlighted Matches */
.ss-hit-title mark { 
    background-color: rgba(255, 0, 85, 0.1);
    color: #ff0055;
}

6. Developer Hooks

SwiftSearch provides several filter hooks and DOM events allowing developers to programmatically customize indexing, styling, search behaviors, and track events.

PHP Actions & Filters

swift_search_algolia_post_document (Filter)
Modify or append custom fields to the document data array before it gets synced to Algolia.

add_filter('swift_search_algolia_post_document', function($document, $post_id, $post) {
    // Example: Add a custom field to the indexed document
    $custom_meta = get_post_meta($post_id, 'my_custom_field', true);
    if (!empty($custom_meta)) {
        $document['my_custom_field'] = sanitize_text_field($custom_meta);
    }
    return $document;
}, 10, 3);

swift_search_algolia_should_index_post (Filter)
Conditionally control whether a post should be indexed into Algolia.

add_filter('swift_search_algolia_should_index_post', function($should_index, $post_id, $post) {
    // Example: Exclude products that are out of stock
    if ($post->post_type === 'product' && function_exists('wc_get_product')) {
        $product = wc_get_product($post_id);
        if ($product && !$product->is_in_stock()) {
            return false;
        }
    }
    return $should_index;
}, 10, 3);

swift_search_algolia_settings (Filter)
Customize index settings before deployment to Algolia, including searchable attributes, custom ranking rules, and facets:

add_filter('swift_search_algolia_settings', function($settings, $config, $base_index_name) {
    // Make custom field searchable and filterable
    $settings['searchableAttributes'][] = 'my_custom_field';
    $settings['attributesForFaceting'][] = 'searchable(my_custom_field)';

    // Add custom ranking rules
    $settings['customRanking'] = array('desc(total_sales)', 'desc(date)');

    return $settings;
}, 10, 3);

swift_search_algolia_vars (Filter)
Modify frontend JS configuration parameters (e.g. adjust multi-currency format, dynamic limits) before they are passed to the frontend browser runtime.

add_filter('swift_search_algolia_vars', function($vars, $settings) {
    // Example: Force search to prioritize a custom currency symbol
    $vars['currencySymbol'] = '€';
    return $vars;
}, 10, 2);

Frontend JavaScript Custom Events

SwiftSearch dispatches native JavaScript events on the document node during various lifecycle states:

• swiftsearch:init: Fired when the search input is mounted and ready.
• swiftsearch:results: Fired after hits are rendered. Passes detail payload containing results and query meta.
• swiftsearch:select: Fired when a user clicks or selects a search hit item.

document.addEventListener('swiftsearch:results', function(event) {
    console.log('Search Query:', event.detail.query);
    console.log('Hits Found:', event.detail.count);
});

7. WP-CLI Commands

SwiftSearch includes native command-line support via WP-CLI. This is highly recommended for developers and system administrators managing large catalogs (10,000+ items) to bypass PHP execution time limits and local server loopback restrictions.

Bulk Indexing

Perform a complete, fast bulk index of all active post types directly via SSH terminal. Bypasses the browser AJAX and local HTTP request stack completely:

wp swift-search-algolia index

Available Options:

• --batch-size=<number>: Number of posts/products to process and import in each Algolia request. (Default: 250).
• --offset=<number>: Skip the first N items before starting. Useful for resuming an interrupted sync or splitting up massive catalogs. (Default: 0).
• --limit=<number>: Only index a maximum of N items in this run. (Default: no limit).

Examples:

# Index posts 0 to 5000 in batches of 500
wp swift-search-algolia index --offset=0 --limit=5000 --batch-size=500

# Resume and index posts 5000 to 10000
wp swift-search-algolia index --offset=5000 --limit=5000 --batch-size=500

Check Index & Connection Status

Inspect server connectivity, verify document counts, and inspect active Algolia indices:

wp swift-search-algolia status

Reset & Recreate Indices

Drop existing Algolia indices and rebuild the settings and sorting replicas from scratch:

wp swift-search-algolia reset

8. Troubleshooting & FAQ