# Search

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](/search.md).


## 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.


::tabs

::tab antlers
```antlers
{{ 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 }}
```
::tab blade
```blade
<s:search:results as="results">
  @forelse($results as $result)
    <a href="{{ $result->url }}" class="result">
      <h2>{{ $result->title }}</h2>
      <p>{{ Statamic::modify($result->content)->truncate(240) }}</p>
    </a>
  @empty
    <h2>No results.</h2>
  @endforelse
</s:search:results>
```

:::tip
When using Blade, make sure to alias your search results if you want to use variables like `$no_results`!
:::

::

## 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>
```

## Multiple Sites

On [multi-site](/multi-site.md) installations, you can search within a specific site, a subset of sites, or across all of them.

::tabs

::tab antlers
```antlers
{{ search:results site="one" }}

{{ search:results site="one|two" }}

{{ search:results site="*" }}
```
::tab blade
```blade
<s:search:results site="one" />

<s:search:results site="one|two" />

<s:search:results site="*" />
```
::

If you omit the `site` parameter, results will be scoped to the current site.

:::tip
When using `supplement_data="false"` with multiple sites, make sure the `site` field is indexed — otherwise results will be filtered out. See [Supplementing Data](#supplementing-data) below.
:::

## 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.

::tabs

::tab antlers
```antlers
{{ search:results supplement_data="false" }}
```
::tab blade
```blade
<s:search:results supplement_data="false">
  ...
</s:search:results>
```
::

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
::tabs
::tab antlers
```
{{ search:results }}
  {{ search_snippets:title | implode(' … ') | mark }}
{{ /search:results }}
```
::tab blade
```blade
<s:search:results as="results">
  @foreach ($results as $result)
    {!! Statamic::modify($result->search_snippets['title'])->implode(' … ')->mark() !!}
  @endforeach
</s:search:results>
```
::

### Algolia
Highlights are typically always available via `search_highlights`. The more powerful feature, [snippets](https://www.algolia.com/doc/api-reference/api-parameters/attributesToSnippet/), are available via `search_snippets` if you configure your index to use them. For example:

```php
'indexes' => [
    'default' => [
        'driver' => 'algolia',
        'settings' => [ // [tl! **:start]
            'attributesToSnippet' => [
                'title:40',
                'teaser:40',
            ],
            'highlightPreTag' => '<mark>',
            'highlightPostTag' => '</mark>',
        ], // [tl! **:end]
    ],
]
```

::tabs

::tab antlers
```antlers
{{ search:results }}
  {{ search_snippets:title:value }}
  or
  {{ search_highlights:title:value }}
{{ /search:results }}
```
::tab blade
```blade
<s:search:results as="results">
  @foreach ($results as $result)
    {{ $result->search_snippets['title']['value'] }}
    or
    {{ $result->search_highlights['title']['value'] }}
  @endforeach
</s:search:results>
```

:::tip
Calling `$result->searchSnippets()` without any arguments returns an array with all search snippets!
:::
::