Search-Result Data Source
Overview
The search-result data source runs a full-text search against the Catalog API and returns matching content items. The search phrase is provided via the phrase config property, which is typically bound to a URL query parameter or context value set by the search Input component.
When to use this
Use search-result on any view that displays the outcome of a user's search query. The phrase property drives what is searched — when it resolves to an empty value, the data source returns an empty list, which is the correct idle state.
Basic Example
{
"type": "search-result",
"contextKey": "results",
"phrase": "$context.phrase",
"batchSize": 20,
"filter": {
"publication": {
"id": { "value": ":publicationId" }
}
}
}$context.phrase is typically populated from the URL query param ?phrase=... at runtime.
Configuration
Type-specific properties
Property | Type | Default | Description |
|---|---|---|---|
phrase | string | — | Required. The search phrase. Supports $context interpolation — e.g. "$context.phrase" reads from the URL query param ?phrase=... |
filter | object | — | Scope the search to a subset of content |
sort | array | — | Controls result ordering (default: relevance) |
searchFields | string[] | ['CONTENT', 'CONTENT_NAME'] | Fields to search in |
searchOptions | object | — | Additional search API options |
limitCharactersBeforeHit | number | — | Trim excerpt to at most N characters before the first highlighted hit |
groupBy | object | — | Deprecated. Group results by a custom content property — requires legacyMode.unwrapBundles which is itself deprecated |
For common properties (contextKey, limit, batchSize, etc.) see Data Sources Overview
Filter properties
Uses the same filter shape as the content data source (StorefrontContentFilter).
Filter key | Type | Description |
|---|---|---|
publication | PublicationFilter | Restrict results to a specific publication — use publication.id |
contentType | { value, negated? } | Limit results to a content type: post, issue, bundle |
taxonomies | TaxonomyListFilter | Restrict results to specific taxonomy nodes |
properties | MapFilter | Filter by custom content properties |
Supports AND, OR, and condition — see da.
Sort properties
Sort key | Type | Description |
|---|---|---|
relevance | { direction } | Sort by relevance score (default) |
publicationDate | { direction } | Sort by publication date |
direction accepts ASC or DESC.
Advanced Features
Showing results only when a query exists
Wrap the result list in a condition:
{
"condition": {
"value": "$context.phrase",
"operation": "SET"
}
}Trimming excerpts
Use limitCharactersBeforeHit to prevent very long excerpts with the search hit far from the start:
{
"type": "search-result",
"phrase": "$context.phrase",
"limitCharactersBeforeHit": 100
}Testing Notes / Edge Cases
- Empty phrase = no results: When phrase resolves to an empty string or undefined, the data source returns zero items. Always pair with a "no results" empty state.
- preventSSRCache: Search results are user-driven — set preventSSRCache: true on server-rendered search pages.
- Short queries: Very short phrases (1–2 characters) may return unexpected results depending on API configuration.