The VTEX Search Result app is a store component that handles with the result of our Search API, and this app is used by store theme.

📢 Disclaimer: Don't fork this project; use, contribute, or open issue with your feature request.

This are the current supported blocks in this repository. Blocks not mentioned are deprecated.

search-result now supports a flexible layout and has all its benefits, specially using the flex-layout block.

You now have access to search-result-layout, it supports three differents blocks: search-result-layout.desktop, search-result-layout.mobile, search-not-found-layout.

search-result-layout.desktop is rendered when user is using a desktop. The .mobile interface is rendered (if provided), when user is using a mobile device. If the .mobile is not provided, the .desktop will be used.

The search-not-found-layout is used (if provided) when the user searches for a term that returns nothing. Important notice: if the user lands on a search page and adds filters until it reachs a empty search, this block will not be rendered!

We also created the search-result-layout.customQuery. If you want to display a custom search-result, by passing a custom querySchema, this block should be used. search-result-layout does not read the values of a querySchema prop!

To pass parameters to the search displayed at search-result-layout you should use the context props in store.search. Example:

"store.search": {
    "blocks": [
      "search-result-layout"
    ],
    "props": {
        "context": {
           "orderByField": "OrderByReleaseDateDESC",
            "hideUnavailableItems": true,
            "maxItemsPerPage": 8
        }
     }
  },

If you want to use the .customQuery:

"store.home": {
  "blocks": [
    "carousel#home",
     "shelf#home",
    "search-result-layout.customQuery#home"
  ]
},
"search-result-layout.customQuery#home": {
  "props": {
    "querySchema": {
      "orderByField": "OrderByReleaseDateDESC",
      "hideUnavailableItems": true,
      "maxItemsPerPage": 8,
      "queryField": "clothing",
      "mapField": "c"
    }
  },
  "children": ["search-result-layout.desktop"]
}

In order to be used inside the flexbile block, we created: breadcrumb.search, search-fetch-more, search-content, search-products-count-per-page, filter-navigator.v3, total-products.v2, order-by.v2 & search-title.v2.

Noticeable notes:

• search-fetch-more renders the fetch more button or the loading spinner, depending on your pagination type.
• search-content renders the gallery or the not-found block, depending on the products returned for the specified filters.
• search-products-count-per-page renders the current products count displayed.
• All *.v2 or .v3 is just a version bump, no changes in behaviour, the changes are that the new components now fetch the data from the search page context and should only be used in the flexible layout. Also changes the wrapper css class, usually by just adding a --layout to the previous used class (like filters to filters--layout).

Read more at the Max Items Per Page Usage section.

We ask for users, from now on, to use the filter-navigator.v2 block if you want to keep updated with the most up to date Filter Navigator in your search-result.

The correct way to use it is setting it in your blocks.json like:

json
"search-result": {
    "blocks": [
      "filter-navigator.v2",
      "gallery",
      "not-found",
      "breadcrumb",
      "order-by",
      "total-products"
    ],
  }

Or via Storefront.

Disclaimer: this notice is deprecated, please use the search-result-layout block. A search-result block may appear in two different contexts, (a) in a search result page (store.search) or (b) as a block in your home page (store.home).

In case of (a) we can configure the search parameters in a search context in the following way:

  "store.search": {
    "blocks": [
      "search-result"
    ],
    "props": {
        "context": {
           "orderByField": "OrderByReleaseDateDESC",
            "hideUnavailableItems": true,
            "maxItemsPerPage": 8
        }
     }
  },
 "store.search#category": {
    "blocks": [
      "search-result"
    ],
    "props": {
        "context": {
           "orderByField": "OrderByReleaseDateDESC",
            "hideUnavailableItems": true,
            "maxItemsPerPage": 8
        }
     }
  },
  "store.search#brand": {
    "blocks": [
      "search-result"
    ],
    "props": {
        "context": {
           "orderByField": "OrderByReleaseDateDESC",
            "hideUnavailableItems": true,
            "maxItemsPerPage": 8
        }
     }
  },
  "store.search#department": {
    "blocks": [
      "search-result"
    ],
    "props": {
        "context": {
           "orderByField": "OrderByReleaseDateDESC",
            "hideUnavailableItems": true,
            "maxItemsPerPage": 8
        }
     }
  },
  "store.search#subcategory": {
    "blocks": [
      "search-result"
    ],
    "props": {
        "context": {
           "orderByField": "OrderByReleaseDateDESC",
            "hideUnavailableItems": true,
            "maxItemsPerPage": 8
        }
     }
  }

Note that only in this case, the parameters must be passed in the context prop of the store.search block. Also remember that we have different store.search blocks e you may configure them in different ways. You may configure a brand search (ended with /b), have 6 items per page, while a department search page, that number may be 12.

Search examples: Free search: https://storetheme.vtex.com/shirt?map=ft. Falls on: store.search. Departament: https://storetheme.vtex.com/decoration/d. Falls on: store.search#department. Category: https://storetheme.vtex.com/bags/necessaire. Falls on: store.search#category Subcategory: https://storetheme.vtex.com/decoration/smartphones/bateria. Falls on:store.search#subcategory. Brand: https://storetheme.vtex.com/kawasaki/b. Falls on:store.search#brand`.

Now for option (b), when we want to show the search-result block outse of a search page, like in the home page, the same parameters must be passed on a different way.

At our example, we want to show a search-result inside a store.home. We put this inside our blocks.json:

"store.home": {
  "blocks": [
    "carousel#home",
    "shelf#home",
    "search-result#home"
  ]
}

Now, to change the search done by this block, we must pass its parameters directly to it, thorugh the querySchema prop:

"store.home": {
  "blocks": [
    "carousel#home",
     "shelf#home",
    "search-result#home"
  ]
},
"search-result#home": {
  "props": {
    "querySchema": {
      "orderByField": "OrderByReleaseDateDESC",
      "hideUnavailableItems": true,
      "maxItemsPerPage": 8
    }
  }
}

See our LTS policy for more information.

• Usage
  • Blocks API
    • Configuration
  • Styles API
    • CSS namespaces
• Troubleshooting
• Contributing
• Tests

This app uses our store builder with the blocks architecture. To know more about Store Builder click here.

We add the search-result as a block in our Store.

To configure or customize this app, you need to import it in your dependencies in manifest.json.

  dependencies: {
    "vtex.search-result": "3.x"
  }

Then, add search-result block into your app theme as we do in our Store theme app.

Now, you can change the behavior of the search result block that is in the store header. See an example of how to configure:

  "search-result#department": {
    "blocks": [
      "filter-navigator.v2",
      "gallery",
      "not-found",
      "breadcrumb",
      "order-by",
      "total-products",
      "search-title"
    ],
    "props": {
      "context": {
        "maxItemsPerPage": 2,
        "orderByField": "OrderByReleaseDateDESC"
      },
      "hiddenFacets": {
        "layoutMode1": "normal",
        "layoutMode2": "small",
        "specificationFilters": {
          "hiddenFilters": []
        }
      },
      "pagination": "show-more"
    }
  },

When implementing this app as a block, various inner blocks may be available. The following interface lists the available blocks within search result and describes if they are required or optional.

"search-result": {
    "allowed": [
      "not-found",
      "breadcrumb",
      "filter-navigator",
      "total-products",
      "order-by",
      "search-title"
    ],
    "required": [
      "gallery"
    ],
    "component": "index"
  },

The search-result has as a required block the gallery. So, any search-result block implementation created must add a gallery as a block that is inside of search-result. Similarly, gallery has its own inner block structure that can be configured that you can see below.

 "gallery": {
    "required": [
      "product-summary"
    ],
    "component": "Gallery"
  }

The gallery has as a required block the product-summary. So, any gallery block implementation created must add a product-summary as a block that is inside of gallery. (Similarly, product-summary has its own inner block structure that can be configured. There is a link to its API in the next section.)

These properties can be changed in the blocks.json file of your theme.

This prop controls the way search results are displayed on mobile. The default values are shown below.

Notice that the default behavior for your store will be the one defined by the mode1. If you want the user to be able to switch between two modes, you must specify the mode2 prop. If only the mode1 is provided, the layout switcher will not be shown and search results will always be rendered according to mode1.

Also, you can configure the product summary that is defined on search-result. See here the Product Summary API.

This app provides some CSS classes as an API for style customization.

To use this CSS API, you must add the styles builder and create an app styling CSS file.

1. Add the styles builder to your manifest.json:

  "builders": {
    "styles": "1.x"
  }

2. Create a file called vtex.searchResult.css inside the styles/css folder. Add your custom styles:

.container {
  margin-top: 10px;
}

Below, we describe the namespaces that are defined in the search-result.

| categoriesContainer | The container for the department filters | DepartmentFilters | | categoryGroup | Container for each category group in the department filters | CategoryFilter | | categoryParent | View of the parent category of this group | CategoryFilter |

You can check if others are experiencing similar issues here. Also feel free to open issues.

Check it out how to contribute with this project.

To execute our tests go to react/ folder and run npm test