Add Filters

Filtering is a critical feature that enhances the user experience by helping users quickly narrow down search results to what’s most relevant to them. While the API does not have a built-in filtering feature, there are two primary strategies you can employ to achieve this functionality:

1. Separate Sources: Create a dedicated source for each filter category and query it based on user selection.
2. Metadata Selectors: Enrich your content with metadata, allowing for flexible, dynamic filtering directly within the search results.

This guide explains these approaches, outlines their pros and cons, and helps you choose the best method for your use case.

Approach 1: Creating Separate Sources

This approach involves creating distinct sources, each representing a specific filter category. For instance, you could have one source for “Articles” and another for “Products,” each searched by its own API widget. When a user selects a filter, your application queries the widget for that category to retrieve the results.

Key Points

• Simplicity: This method is straightforward and requires minimal client-side logic.
• Static Filters: Each source is predefined and corresponds to a specific category.
• Limitations: Items can only belong to one filter category, making it challenging to handle overlapping or combined filters.
• Maintenance: Managing multiple sources and widgets can become cumbersome as the number of filters grows.

This method is suitable for simple, static filtering needs where categories are mutually exclusive and the filtering logic is straightforward.

Approach 2: Using Metadata Selectors

In this approach, each item in your sources is enriched with metadata fields such as type, tags, or categories. These fields allow you to define multiple properties for an item, enabling dynamic and flexible filtering directly on the client side.

Key Points

• Flexibility: Supports dynamic filtering and allows items to belong to multiple categories simultaneously.
• Dynamic Filters: Filters can be combined to narrow down results further (e.g., items that are both “Featured” and “Documentation”).
• Client-Side Logic: Filtering happens programmatically in your application, providing full control over how results are displayed.
• Setup Complexity: Requires thoughtful planning of metadata and of how your sources are set up.

To learn how to enrich your content with metadata, refer to the Search Results Customization Guide.

This method is ideal for complex or dynamic filtering needs, such as when items need to belong to multiple categories or when filters need to be combined in various ways.

Recommendations

The choice between the two approaches depends on your specific requirements:

• Use Separate Sources if you have simple, static filtering needs and do not require combined or overlapping filters.
• Choose Metadata Selectors for modern, dynamic filtering needs where flexibility, multiple categories, and combined filters are essential.

For most use cases, metadata selectors provide the flexibility needed to create a richer, more user-friendly filtering experience.