---
title: predictiveSearch - Storefront API
description: >
  Returns suggested results as customers type in a search field, enabling
  type-ahead search experiences. The query matches
  [products](/docs/api/storefront/2026-01/objects/Product),
  [collections](/docs/api/storefront/2026-01/objects/Collection),
  [pages](/docs/api/storefront/2026-01/objects/Page), and
  [articles](/docs/api/storefront/2026-01/objects/Article) based on partial
  search terms, and also provides [search query
  suggestions](/docs/api/storefront/2026-01/objects/SearchQuerySuggestion) to
  help customers refine their search.


  You can filter results by resource type and limit the quantity. The
  [`limitScope`](/docs/api/storefront/2026-01/queries/predictiveSearch#arguments-limitScope)
  argument controls whether limits apply across all result types or per type.
  Use
  [`unavailableProducts`](/docs/api/storefront/2026-01/queries/predictiveSearch#arguments-unavailableProducts)
  to control how out-of-stock products appear in results.
api_version: 2026-01
api_name: storefront
type: query
api_type: graphql
source_url:
  html: 'https://shopify.dev/docs/api/storefront/latest/queries/predictiveSearch'
  md: 'https://shopify.dev/docs/api/storefront/latest/queries/predictiveSearch.md'
---

# predictive​Search

query

Returns suggested results as customers type in a search field, enabling type-ahead search experiences. The query matches [products](https://shopify.dev/docs/api/storefront/2026-01/objects/Product), [collections](https://shopify.dev/docs/api/storefront/2026-01/objects/Collection), [pages](https://shopify.dev/docs/api/storefront/2026-01/objects/Page), and [articles](https://shopify.dev/docs/api/storefront/2026-01/objects/Article) based on partial search terms, and also provides [search query suggestions](https://shopify.dev/docs/api/storefront/2026-01/objects/SearchQuerySuggestion) to help customers refine their search.

You can filter results by resource type and limit the quantity. The [`limitScope`](https://shopify.dev/docs/api/storefront/2026-01/queries/predictiveSearch#arguments-limitScope) argument controls whether limits apply across all result types or per type. Use [`unavailableProducts`](https://shopify.dev/docs/api/storefront/2026-01/queries/predictiveSearch#arguments-unavailableProducts) to control how out-of-stock products appear in results.

## Arguments

* limit

  [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int)

  Limits the number of results based on `limit_scope`. The value can range from 1 to 10, and the default is 10.

* limit​Scope

  [Predictive​Search​Limit​Scope](https://shopify.dev/docs/api/storefront/latest/enums/PredictiveSearchLimitScope)

  Decides the distribution of results.

* query

  [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String)

  required

  The search query.

* searchable​Fields

  [\[Searchable​Field!\]](https://shopify.dev/docs/api/storefront/latest/enums/SearchableField)

  Specifies the list of resource fields to use for search. The default fields searched on are TITLE, PRODUCT\_TYPE, VARIANT\_TITLE, and VENDOR. For the best search experience, you should search on the default field set.

  The input must not contain more than `250` values.

* types

  [\[Predictive​Search​Type!\]](https://shopify.dev/docs/api/storefront/latest/enums/PredictiveSearchType)

  The types of resources to search for.

  The input must not contain more than `250` values.

* unavailable​Products

  [Search​Unavailable​Products​Type](https://shopify.dev/docs/api/storefront/latest/enums/SearchUnavailableProductsType)

  Specifies how unavailable products are displayed in the search results.

***

## Possible returns

* Predictive​Search​Result

  [Predictive​Search​Result](https://shopify.dev/docs/api/storefront/latest/objects/PredictiveSearchResult)

  Returned by the [`predictiveSearch`](https://shopify.dev/docs/api/storefront/2026-01/queries/predictiveSearch) query to power type-ahead search experiences. Includes matching [`Product`](https://shopify.dev/docs/api/storefront/2026-01/objects/Product), [`Collection`](https://shopify.dev/docs/api/storefront/2026-01/objects/Collection), [`Page`](https://shopify.dev/docs/api/storefront/2026-01/objects/Page), and [`Article`](https://shopify.dev/docs/api/storefront/2026-01/objects/Article) objects, along with query suggestions that help customers refine their search.

  * articles

    [\[Article!\]!](https://shopify.dev/docs/api/storefront/latest/objects/Article)

    non-null

    The articles that match the search query.

  * collections

    [\[Collection!\]!](https://shopify.dev/docs/api/storefront/latest/objects/Collection)

    non-null

    The articles that match the search query.

  * pages

    [\[Page!\]!](https://shopify.dev/docs/api/storefront/latest/objects/Page)

    non-null

    The pages that match the search query.

  * products

    [\[Product!\]!](https://shopify.dev/docs/api/storefront/latest/objects/Product)

    non-null

    The products that match the search query.

  * queries

    [\[Search​Query​Suggestion!\]!](https://shopify.dev/docs/api/storefront/latest/objects/SearchQuerySuggestion)

    non-null

    The query suggestions that are relevant to the search query.

***

## Examples

* ### predictiveSearch reference