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.
Block name | Component | Description |
---|---|---|
gallery |
Gallery | Gallery that displays found products |
not-found |
NotFoundSearch | Block containing text and description that search was not found |
search-result-layout |
SearchResultLayout | Layout block that enables user to build a custom search page |
search-result-layout.customQuery |
SearchResultLayoutCustomQuery | Just like search-result-layout but accepts a querySchema prop to execute custom query. |
search-result-layout.desktop |
SearchResultFlexible | Block used to build layout for desktop. |
search-result-layout.mobile |
SearchResultFlexibleMobile | Block used to build layout for mobile. |
search-not-found-layout |
NotFoundLayout | Block used to layout when a user searches for a product that does not exist. |
search-layout-switcher |
LayoutModeSwitcherFlexible | Enables user to switch between layout modes in mobile |
search-content |
SearchContent | Block that chooses to show the gallery block if products are found and not-found if filters selected lead to an empty search |
search-fetch-more |
FetchMore | Renders the fetch more button if pagination is of type show-more . If it is infinite scroll, shows the Loader when bottom of the page is reached |
search-products-count-per-page |
ProductCountPerPage | Shows the total count of products displayed in search at the moment. |
order-by.v2 |
OrderByFlexible | Allows user to pick the type of order of the products displayed. |
filter-navigator.v3 |
FilterNavigatorFlexible | Allows user to apply different filters to search. On mobile, renders a button that shows the sidebar when pressed. |
total-products.v2 |
TotalProductsFlexible | Shows the total products count found for that search. |
search-title.v2 |
SearchTitleFlexible | Display search title according to the search context. |
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 (likefilters
tofilters--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
}
}
}
Release | Status | Initial Release | Maintenance LTS Start | End-of-life | Store Compatibility |
---|---|---|---|---|---|
[3.x] | Current Release | 2018-12-01 | 2.x | ||
[2.x] | Maintenance LTS | 2018-10-02 | 2018-12-01 | March 2019 | 1.x |
See our LTS policy for more information.
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.
Prop name | Type | Description | Default value |
---|---|---|---|
querySchema |
QuerySchema |
Query made when there's no context | N/A |
hiddenFacets |
HiddenFacets |
Indicates which facets will be hidden | N/A |
pagination |
Enum |
Pagination type (values: 'show-more' or 'infinite-scroll') | infinity-scroll |
mobileLayout |
MobileLayout |
Control mobile layout | N/A |
showFacetQuantity |
Boolean |
If quantity of items filtered by facet should appear besides its name on filter-navigator |
false |
blockClass |
String |
Unique class name to be appended to block classes | "" |
showProductsCount |
Boolean |
controls if the quantity of loaded products and total number of items of a search result are displayed under the show more button. |
false |
Prop name | Type | Description | Default value |
---|---|---|---|
maxItemsPerPage |
Number |
Maximum number of items per search page | 10 |
queryField |
String |
Query field | N/A |
mapField |
String |
Map field | N/A |
restField |
String |
Other Query Strings | N/A |
orderByField |
Enum |
Order by field (values: OrderByTopSaleDESC , OrderByReleaseDateDESC , OrderByBestDiscountDESC , OrderByPriceDESC , OrderByPriceASC , OrderByNameASC , OrderByNameDESC or '' (by relevance)) |
'' |
hideUnavailableItems |
Boolean |
Set if unavailable items should show on search | false |
HiddenFacets
Prop name | Type | Description | Default value |
---|---|---|---|
brands |
Boolean |
Hide Brands filter | false |
categories |
Boolean |
Hide Categories filter | false |
priceRange |
Boolean |
Hide Price filter | false |
specificationFilters |
SpecificationFilters |
Hide Specifications filters | N/A |
Prop name | Type | Description | Default value |
---|---|---|---|
hideAll |
Boolean |
Hide specifications filters | false |
hiddenFilters |
Array(HiddenFilterUnit) |
Array of specifications filters that should be hidden | N/A |
HiddenFilterUnit
Prop name | Type | Description | Default value |
---|---|---|---|
name | String! | Name of Hidden specification filter | "" |
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
.
Prop name | Type | Description | Default value |
---|---|---|---|
mode1 |
Enum |
Layout mode of the switcher (values: 'normal', 'small' or 'inline') | normal |
mode2 |
Enum |
Layout mode of the switcher 2 (values: 'normal', 'small' or 'inline') | small |
Prop name | Type | Description | Default value |
---|---|---|---|
preventRouteChange |
Boolean |
Prevents route change when selecting filters, using the query string instead. Intended for search-result blocks inserted on custom pages with static routes. |
false |
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.
- Add the
styles
builder to yourmanifest.json
:
"builders": {
"styles": "1.x"
}
- Create a file called
vtex.searchResult.css
inside thestyles/css
folder. Add your custom styles:
.container {
margin-top: 10px;
}
Below, we describe the namespaces that are defined in the search-result.
Token name | Description | Component Source |
---|---|---|
container |
The main container of search-result | SearchResult |
buttonShowMore |
Show the see more button | ShowMoreLoaderResult |
showingProducts |
Text below the show mnore button | ShowMoreLoaderResult |
showingProductsCount |
The range part of the text below the show more button | ShowMoreLoaderResult |
switch |
Layout mode switcher container | SearchResult |
breadcrumb |
Breadcrumb container | SearchResult |
filter |
Filter option container | FilterOptionTemplate |
resultGallery |
Gallery result container | SearchResult |
border |
Order by container border | SearchResult |
gallery |
The main container of gallery | Gallery |
filterPopupButton |
Filter pop-up button | FilterSideBar |
accordionFilter |
Accordion filter container | AccordionFilterContainer |
filterAccordionItemBox |
Accordion filter item container | AccordionFilterItem |
filterAccordionBreadcrumbs |
Filter accordion breadcrumbs container | AccordionFilterContainer |
filterButtonsBox |
Filter buttons container | FilterSidebar |
filterPopupFooter |
Filter pop-up footer container | Popup |
accordionFilterItemOptions |
Accordion filter item options container | AccordionFilterItem |
dropdownMobile |
The main container of drop-down on mobile | SelectionListOrderBy |
accordionFilterItemActive |
Container of the accordion filter item when it is active | AccordionFilterItem |
totalProducts |
The main container of total-products | TotalProducts |
orderBy |
The main container of order-by | OrderBy |
accordionFilterItemHidden |
Accordion filter item container when it is hidden | AccordionFilterItem |
accordionFilterItem |
Accordion filter item container | AccordionFilterItem |
accordionFilterItemBox |
Accordion filter item box | AccordionFilterItem |
accordionFilterItemTitle |
Accordion filter item title container | AccordionFilterItem |
accordionFilterItemIcon |
Accordion filter item icon container | AccordionFilterItem |
filterAvailable |
Filter option template main container when it is available | FilterOptionTemplate |
filterSelected |
Filter option template main container when it is selected | FilterOptionTemplate |
filterPopupTitle |
Filter pop-up title label | FilterSidebar |
filterPopupArrowIcon |
Filter pop-up arrow icon container | FilterSidebar |
footerButton |
Footer button | FooterButton |
layoutSwitcher |
Layout mode switcher container | LayoutModeSwitcher |
filterPopup |
Main container of filter pop-up | FilterPopup |
filterPopupOpen |
Main container of filter pop-up when it is open | FilterPopup |
filterPopupContent |
Filter pop-up content | Popup |
filterPopupContentContainer |
Filter pop-up content container | Popup |
filterPopupContentContainerOpen |
Filter pop-up content container when it is open | Popup |
galleryItem |
Gallery item container | Gallery |
searchNotFound |
Main container of Search Not Found | NotFoundSearch |
filterContainer |
Filter container | FilterNavigator |
filterContainer--title |
Title's filter container | FilterNavigator |
filterContainer--selectedFilters |
Selected filters' filter container | SelectedFilters |
filterContainer--c |
Department's filter container | DepartmentFilters |
filterContainer--b |
Brand's filter container | FilterOptionTemplate |
filterContainer--priceRange |
Price range's filter container | PriceRange |
filterContainer-- + FACET_TYPE |
FACET_TYPE's filter container | FilterOptionTemplate |
filterTitle |
Filter title container | FilterOptionTemplate |
filterIcon |
Filter icon container | FilterOptionTemplate |
galleryTitle |
Category name or search term title | Title |
filterItem |
Checkbox and label for Filters (desktop only) | SearchFilter |
filterItem-- + FACET_VALUE |
FACET_VALUE's checkbox and label for Filters (desktop only) | SearchFilter |
filterItem--selected |
Checkbox and label for selected Filters (desktop only) | SearchFilter |
selectedFilterItem |
Checkbox and label for selected Filters (desktop only) | SelectedFilters |
orderByButton |
the "Sort By" button found on search results | SelectionListOrderBy |
orderByDropdown |
the dropdown that appears when the "Sort By" button found on search results is pressed | SelectionListOrderBy |
orderByOptionsContainer |
the container with the "Order by" options of the "Sort by" button | SelectionListOrderBy |
orderByOptionItem |
the "Order by" option that appears in the container of the "Sort by" button | SelectionListOrderBy |
| 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