> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# Method name: facets(facets: Array<string>)

# Method package: wixSearch

# Method menu location: wixSearch --> WixSearchBuilder --> facets

# Method Link: https://dev.wix.com/docs/velo/apis/wix-search/wix-search-builder/facets.md

# Method Description:

Categorizes search results according to the specified facets.

The `facets()` function allows you to categorize search results according to one or more
 specified fields.

 For example, if you have a sports equipment store with products divided into `collections` 
 of `Basketball`, `Football`, and `Baseball` equipment, you can apply `collections` as a facet to your search 
 and get information about how many documents in the search results are included in each collection. 

 If you chained a `facets()` function to your search, your [`WixSearchResult`](wix-search.WixSearchResult.html) 
 will include an array of [facet results](wix-search.WixSearchResult.html#facets). 

 Faceting is a useful tool for presenting categorization data to site visitors 
 and allowing them to narrow down and navigate search results. 
 Visitors can select one or more facets, and you can apply corresponding filters to your search results.

![Facet Example](https://wixmp-833713b177cebf373f611808.wixmp.com/images/velo-images/media_faceting_tshirts4.png "Facet Example")
 
 By default, `facets()` is set to none.

 You cannot apply facets to your search if the [`documentType`](#documentType) is set to `"Site/Pages"`. 

 Only some fields can be used for faceting. You can check which fields are facetable in the schema for each [`documentType`](#documentType).



# Method Code Examples:

*** Note: do not assume any prop names or enum values other than the ones in the example.

## Add a single facet to a search

```javascript
let newSearch = search
  .documentType("Stores/Products")
  .facets("inStock");
```

## Add multiple facets to a search

```javascript
let newSearch = search
  .documentType("Forum/Content")
  .facets("likeCount", "viewCount");
```

## Create a search, add facets to it, and run it

```javascript
import wixSearch from 'wix-search';

// ...

wixSearch.search()
  .documentType("Stores/Products")
  .facets("collections", "inStock")
  .find()
  .then( (results) => {
    const facets = results.facets;
  })
  .catch( (error) => {
    console.log(error);
  });

 /* Example facets array
  * 
  * [
  *   {
  *     "facet": "collections",
  *     "facets":
  *       [
  *         {
  *           "facetValue": "Winter",
  *           "count": 29
  *         },
  *         {
  *           "facetValue": "Spring",
  *           "count": 17
  *         },
  *         {
  *           "facetValue": "Summer",
  *           "count": 36
  *         }
  *       ]
  *   },
  *   {
  *     "facet": "inStock",
  *     "facets":
  *       [
  *         {
  *           "facetValue": "true",
  *           "count": 67
  *         },
  *         {
  *           "facetValue": "false",
  *           "count": 15
  *         }
  *       ]
  *   }
  * ]
  * 
  */
```

## Filter search results according to selected facets

```javascript
import wixSearch from 'wix-search';

$w.onReady(function () {

  // Define what happens when the facet repeater's data is set
  $w("#facetRepeater").onItemReady(($item, itemData) => {
    $item("#facetText").text = itemData.facetValue;
    $item("#facetNumberText").text = "(" + itemData.count + ")";

    // When a facet is selected, run the function
    // that displays only the selected products
    $item("facetText").onClick(event => {
      const facet = $item("#facetText").text;
      displaySelectedProducts(facet);
    });
  });

  // Define what happens when the product repeater's data is set
  $w("productRepeater").onItemReady(($item, itemData) => {
    $item("#productTitleText").text = itemData.title;
    $item("#productDescriptionText").text = itemData.description;
    $item("#productImage").src = itemData.image;
  });
  
  // Run a search which applies a facet that categorizes store
  // products according to the collection they belong to
  wixSearch.search()
  .documentType("Stores/Products")
  .facets("collections")
  .find()
  .then((results) => {

      // Get the first (and only) facet result
      const facets = results.facets[0].facets;

      // Add an ID to each object in the facets 
      // array (required for repeater data)
      const newFacets = facets.map((facet) => {
        facet._id = facet.facetValue;
        return facet;
      });
      
      // Set the facet repeater's data
      $w('#facetRepeater').data = newFacets;
      // Set the initial pre-filtered product repeater's data 
      $w('#productRepeater').data = results.documents;
    });
});

// Display only products from the collection 
// corresponding to the selected facet
export function displaySelectedProducts(facet) {
  wixSearch.search()
  .documentType("Stores/Products")
  .hasSome("collections", [facet])
  .find()
  .then((results) => {
    $w('#productRepeater').data = results.documents;
  });
}
```

---