VTEX Developer Portal

Building a search results page with multiple layouts

To obtain successful results with this recipe, it is strongly recommended to understand previously how the Flex Layout and the Search Result apps work. We also advise you to go through the Building a Horizontal Product Summary recipe to achieve similar results on your search results page.

Your results presentation on the search results page doesn't need to be always the same for your users: thanks to enhancements in the Search Result app, you can provide them a more customized experience to navigate between the fetched products.

multiple-layoutsmultiple-layouts
Notice that the search results page above works two different layouts: grid and list.

The flexibility to offer multiple layouts, which can help the sales taxes by enhancing the shopping experience, is at hands! Check out the step-by-step section below.

Step by step

  1. Implement the Search Result app in your Store Theme according to the instructions in the documentation.
  2. When declaring the gallery block responsible for structuring the page layout, use its layouts prop to define the desired layouts for the search results page. For example:
"gallery": {
  "props": {
    "layouts": [
      {
        "name": "grid",
        "component": "GridSummary",
        "itemsPerRow": {
          "(min-width:1300px)": 4,
          "desktop": 3,
          "tablet": 3,
          "phone": 2
        }
      },
      {
        "name": "list",
        "component": "ListSummary",
        "itemsPerRow": 1
      }
    ],
    "ListSummary": "product-summary.shelf#listLayout",
    "GridSummary": "product-summary.shelf"
  }
}

According to the code above, the search results page will count on two different layouts, namely grid and list. The component prop is defining the name of the gallery's prop that, in turn, will declare the parent block responsible for defining the layout's components. Both of them (product-summary.shelf#listLayout and product-summary.shelf blocks) should be declared by you in the code to build the desired pages. Finally, the itemsPerRow prop controls how many items per row should be displayed by each layout.

All of the layouts's three properties - name, component, and itemsPerRow - are mandatory and must be provided for each layout.

  1. Define the default layout i.e. which layout will be first presented to your users using the defaultGalleryLayout prop, from the search-result-layout.mobile and search-result-layout.desktop blocks:
"search-result-layout.desktop": {
  "children": [
    "flex-layout.row#searchbread",
    "flex-layout.row#searchtitle",
    "flex-layout.row#result"
  ],
  "props": {
    "pagination": "show-more",
    "preventRouteChange": false,
    "defaultGalleryLayout": "grid"
  }
}

Until now, you have a functioning search page with multiple layouts but with no flexibility to switch between them. For this purpose, we are going to declare next the gallery-layout-switcher block.

  1. Declare the gallery-layout-switcher block in the search results template (store.search):
"gallery-layout-switcher": {
  "children": [
    /*
      * For accessibility purposes, it is fundamental to define the layout options following the same ordering used to declare them in step 2.
      */
    "gallery-layout-option#grid",
    "gallery-layout-option#list"
  ]
},
"gallery-layout-option#grid": {
  "props": {
    "name": "grid"
  },
  "children": [
    "icon-grid",
    "responsive-layout.desktop#textOptionGrid"
  ]
},
"gallery-layout-option#list": {
  "props": {
    "name": "list"
  },
  "children": [
    "icon-inline-grid",
    "responsive-layout.desktop#textOptionList"
  ]
},
"responsive-layout.desktop#textOptionGrid": {
  "children": [
    "rich-text#option-grid"
  ]
},
"responsive-layout.desktop#textOptionList": {
  "children": [
    "rich-text#option-list"
  ]
},
"rich-text#option-grid": {
  "props": {
    "text": "Grid",
    "textColor": "c-auto",
    "blockClass": "layout-option"
  }
},
"rich-text#option-list": {
  "props": {
    "text": "List",
    "textColor": "c-auto",
    "blockClass": "layout-option"
  }
}

As seen above, each gallery-layout-option block receives the name prop with the name of the layout it corresponds to - this is a mandatory prop. In addition to this, you can also declare other blocks as its children and customize the selected layout option using the galleryLayoutOptionButton--selected CSS Handle.

  1. Add the gallery-layout-switcher block as a child of the search-result-layout.mobile and search-result-layout.desktop blocks to display the switcher button on the page for both devices (mobile and desktop). For example:
"flex-layout.row#searchinfo": {
  "children": ["flex-layout.col#productCount", "flex-layout.row#orderByAndSwitcher"]
},
"flex-layout.row#orderByAndSwitcher": {
  "children": ["order-by.v2", "gallery-layout-switcher"],
  "props": {
    "horizontalAlign": "right",
    "preventHorizontalStretch": true,
    "blockClass": "orderByAndSwitcher",
    "colGap": 3
  }
}
"flex-layout.col#switcherMobile": {
  "children": ["gallery-layout-switcher"],
  "props": {
    "verticalAlign": "middle"
  }
}
  1. Deploy your theme changes.

Updated 10 days ago


Building a search results page with multiple layouts


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.