> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Placeholder search

> Placeholder search returns results when users submit an empty query, allowing you to display default or trending content before the user types anything.

Placeholder search is a search request where the query string `q` is empty or missing. Instead of returning no results, Meilisearch returns documents from the index, respecting all other search parameters such as [filters](/capabilities/filtering_sorting_faceting/getting_started), [sorting](/capabilities/filtering_sorting_faceting/how_to/sort_results), and [facets](/capabilities/filtering_sorting_faceting/how_to/filter_with_facets).

This is useful when you want to display default content on a landing page, show trending items, or let users browse results before they start typing.

## How it works

When Meilisearch receives a search request with an empty query, it skips the text-matching phase entirely. Documents are returned in the order determined by the active [ranking rules](/capabilities/full_text_search/relevancy/ranking_rules), with [custom ranking rules](/capabilities/full_text_search/relevancy/custom_ranking_rules) and the `sort` parameter playing the most significant role.

Since no query terms are involved, text-based ranking rules like `words`, `typo`, `proximity`, and `exactness` have no effect. Only `sort` and custom ranking rules influence the order of results.

## Basic example

Send a search request with an empty query string:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/movies/search' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    --data-binary '{
      "q": ""
    }'
  ```
</CodeGroup>

Meilisearch returns documents from the `movies` index in the default order.

## Placeholder search with filters and sorting

Placeholder search becomes more powerful when combined with filters and sorting. For example, you can show the highest-rated movies in a specific genre:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/movies/search' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    --data-binary '{
      "q": "",
      "filter": "genres = Action",
      "sort": ["rating:desc"]
    }'
  ```
</CodeGroup>

This returns all action movies sorted by rating, without requiring the user to type anything.

## Placeholder search with facets

You can also request facet distributions alongside a placeholder search to build category navigation:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/movies/search' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    --data-binary '{
      "q": "",
      "facets": ["genres", "release_year"]
    }'
  ```
</CodeGroup>

The response includes a `facetDistribution` object showing the count of documents for each facet value.

## Common use cases

* **Landing pages**: Show popular or recent items when a user first visits your search page
* **Category browsing**: Combine an empty query with filters to let users explore content by category
* **Default recommendations**: Sort by a custom ranking attribute like `popularity` to surface trending content
* **Faceted navigation**: Display facet counts to help users narrow down results before searching

## Pagination

Placeholder search supports the same pagination parameters as regular search. Use `offset` and `limit` (or `page` and `hitsPerPage`) to paginate through results:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/movies/search' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    --data-binary '{
      "q": "",
      "limit": 20,
      "offset": 40
    }'
  ```
</CodeGroup>

<Info>
  For a complete list of search parameters, see the [search API reference](/reference/api/search/search-with-post).
</Info>