Skip to content Skip to footer navigation
Light theme Dark theme

Search Tag

This is how you do search. This is the tag you're looking for.

Overview#

An overview on how to configure search, indexing, and the query form can be found in the Search Docs.

Example#

On a search result page, you can loop through the results of the search like they were entries. You'll have access to all the data of all the content of your search results returned so you can format them any way you wish.

{{ search:results }}
 
  {{ if no_results }}
    <h2>No results.</h2>
  {{ else }}
 
    <a href="{{ url }}" class="result">
      <h2>{{ title }}</h2>
      <p>{{ content | truncate:240 }}</p>
    </a>
 
  {{ /if }}
 
{{ /search:results }}
antlers
antlers

Search Forms#

The search form itself — that text box users type into, is a normal, every day HTML form with a search input that submits to a URL containing a search:results tag in the template. Nice and simple.

<form action="/search/results">
    <input type="search" name="q" placeholder="Search">
    <button type="submit">Make it so!</button>
</form>
antlers
antlers

Supplementing Data#

By default, data will be supplemented. This means that while your search indexes can remain lean by only including the fields you actually
want to be searchable, the tag will convert your results into full objects (entries, terms, etc.) which allow you to use any of their fields.

There is an overhead associated with this though, so if all you need is to display values that are in the index, you may disable supplementing.

{{ search:results supplement_data="false" }}
antlers
antlers

This has a few caveats:

  • Only fields that you've indexed will be available.
  • The search tag will filter out any unpublished items by default. If you haven't indexed the status field, you will get no results. Either
    index the status field, or add status:is="" to your tag to prevent the filtering.
  • When using multiple sites, the search tag will filter items for the current site. If you haven't indexed the site field, you will get no results. Either
    index the site field, or add site:is="" to your tag to prevent the filtering.
  • You won't be able to use variables like result_type and search_score.

Contextual Keyword Snippets#

This feature works slightly differently depending on the driver you're using.

Comb / Local#

{{ search:results }}
  {{ search_snippets:title | implode(' … ') | mark }}
{{ /search:results }}
antlers
antlers

Algolia#

Highlights are typically always available via search_highlights. The more powerful feature, snippets, are available via search_snippets if you configure your index to use them. For example:

'indexes' => [
    'default' => [
        'driver' => 'algolia',
        'settings' => [ 
            'attributesToSnippet' => [
                'title:40',
                'teaser:40',
            ],
            'highlightPreTag' => '<mark>',
            'highlightPostTag' => '</mark>',
        ], 
    ],
]
php
php
{{ search:results }}
  {{ search_snippets:title:value }}
  or
  {{ search_highlights:title:value }}
{{ /search:results }}
antlers
antlers

Parameters#

index #

string

The search index to query. Default: default.

query #

string

The query string parameter used for the search term. Default: q.

site #

string

The site you wish to search. If you wish to search in all sites, you can use a wildcard: *. Default: the current site.

limit #

integer

Limit the total results returned.

offset #

integer

Skip the first n number of results.

as #

string

Alias your results into a new variable loop.

supplement_data #

string

When true will include all non-indexed content field. See supplementing data Default: true.

for #

string

The term to be searched for. Overrides the query parameter.

paginate #

boolean|int *false*

Specify whether your results should be paginated. You can pass true and also use the limit param, or just pass the limit directly in here.

page_name #

string *page*

The query string variable used to store the page number (ie. ?page=).

on_each_side #

int *3*

When using pagination, this specifies the max number of links each side of the current page. The minimum value is 1.

chunk #

int

Chunking results can significantly reduce memory usage when loading lots of results. Specify how many results should be included in each "chunk".

Variables#

Variable Type Description

no_results

 boolean

If there are no results.

first

 boolean

If this is the first item in the loop.

last

 boolean

If this is the last item in the loop.

count

 integer

The number of current iteration in the loop.

index

 integer

The zero-based count of the current iteration in the loop.

total_results

 integer

The number of results in the loop. When you're paginating results, this will be the number of results on the current page. If you need to get the total number of results across all pages, you can use {{ paginate:total_items }}.

search_score

 float

The internal relevance score that Statamic given to this result. Helpful for debugging, but useless to the public. Only applies when using the local driver.

result_type

 string

The type of result. e.g. entry, term, asset, etc.

search_snippets

 array

.

_highlightResult

 array

Available when using the Algolia driver. Displays a field with the search term automatically highlighted. Example: {{ _highlightResult:myfield:value }}