catalog.fn.suggest()
Provides autocomplete suggestions for an attribute. Returns matching values based on user input for implementing search-as-you-type, autocomplete, and fuzzy matching features.
Syntax
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
attribute | string | Yes | The attribute to get suggestions for |
value | string | number | Yes | The search term to match against (prefix matching by default, regex with /pattern/ syntax) |
max | number | No | Maximum number of suggestions to return (default: 20) |
transform | ('lowercase' | 'removeWhitespace' | 'trim')[] | No | Normalize values before matching |
calculateResultKeys | boolean | No | Include item keys in results (default: true) |
excludeUndefineds | boolean | No | Exclude undefined values (default: true) |
excludeNulls | boolean | No | Exclude null values (default: true) |
relevantData | 'filtered' | 'all' | 'excludeQuery' | No | Which data to search: 'filtered' (default), 'all', or 'excludeQuery' |
excludeQuery | Partial<DcuplQuery | DcuplQueryGroup> | No | Query to exclude when using relevantData: 'excludeQuery' |
Return Type
Returns an array of Suggestion objects:
Usage Notes
- Use /pattern/ syntax for regex matching (e.g., "/pro/" for contains)
- Empty search term returns all unique values
- Suggestions respect current query filters by default (relevantData: "filtered")
- Use transform options for flexible matching (lowercase, removeWhitespace, trim)
- Performance is optimized - works with large datasets efficiently
- Performance: Set calculateResultKeys: false when you only need values, not item references
- Performance: Use max parameter to limit results - default is 20
- Performance: Avoid regex patterns for simple prefix matching - prefix is faster
- Troubleshooting: Use relevantData: "all" if you want suggestions regardless of current filters
Related Methods
catalog.fn.facets()- Get all unique values with counts for building filterscatalog.query.addCondition()- Apply filters based on selected suggestioncatalog.query.items()- Get items matching the result keys
Examples
Product Search Autocomplete
Basic autocomplete implementation with prefix matching and transform options.
Category Filter Suggestions
Get all category values for a filter dropdown, showing counts based on current filters.
Brand Search with Icons
Enrich suggestions with additional metadata like counts and custom icons.
Color Suggestions with Mapping
Map color suggestions to hex codes or other visual representations.
Country Suggestions with Flags
Enrich country suggestions with flag emojis for visual display.
Course Title with Full Item Lookup
Use suggestion keys to fetch complete item details for rich autocomplete.
Hashtag Suggestions
Handle special characters in input by preprocessing before suggestion.
Campaign Code Suggestions (Uppercase)
Handle uppercase codes with proper transform and display formatting.