📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.

Overlay Layout

All ContributorsAll Contributors

The Overlay Layout app provides blocks that help you create a Dropdown, Select or a Tooltip component.


Example of a Locale Switcher using the Overlay Layout.


  1. Add the Overlay Layout app to your theme's dependencies in the manifest.json, for example:
  "dependencies": {
    "vtex.overlay-layout": "0.x"

Now you can use the two blocks exported by the app:

Block nameDescription
overlay-triggerhttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Declares a renderable children block responsible for triggering the overlay-layout content.
overlay-layouthttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Declares a renderable children block responsible for building the
  1. In any desired theme template, add the overlay-trigger and then declare it using a block of your choosing and the overlay-layout:
  "overlay-trigger": {
    "children": [

Notice that the overlay-trigger is not rendered. Following the example stated above, the rich-text block will be the one rendered and responsible for effectively triggering the Overlay Layout content (defined by the children block of overlay-layout).

overlay-trigger props

Prop nameTypeDescriptionDefault value
triggerEnumDefines whether the popover-layout will be opened by click (click) or hover (hover).click
  1. Configure the chosen trigger block and declare the overlay-layout using its props. For example:
  "rich-text#question": {
    "props": {
      "text": "**Click to open the Overlay Layout**",
      "blockClass": "question"
  "overlay-layout": {
    "props": {
      "placement": "left"
    "children": [
  "rich-text#link": {
    "props": {
      "text": "\n**Reach us at**\nwww.vtex.com.br",
      "blockClass": "link"

The overlay-layout defines which block will be rendered in order to build the Overlay Layout content. This means that you will have to pass to it a children block to be rendered.

overlay-layout props

Prop nameTypeDescriptionDefault value
placementEnumDefines the Overlay Layout content placement when it is triggered according to the Trigger component positioning. Possible values are: bottom, left, right or top. If there is no page space in the placement that you choose, it will fit in a fallback position.bottom
scrollBehaviorEnumDefines the Overlay Layout content behavior when users try to scroll the page. Possible values are: lock-page-scroll (in which users can't scroll), close-on-scroll (the block is closed when users start scrolling) or default (Scroll does not affect the Overlay Layout content).default
backdropEnumOnce the Overlay Layout content is rendered, it defines whether a backdrop overlay will be displayed (visible) or not (none). When set as visible, the backdrop will close Overlay Layout content when clicked on. Otherwise, the content will be closed only if any component from the page is clicked on.none
showArrowBooleanWhether an arrow pointing to the overlay-trigger component should be displayed on UI(true) or not (false).false
offsetsObjectDefines the overlay-layout component positioning when compared to the overlay-trigger (unit used is px). For more details, check out the offsets object table stated below.{ skidding: 0, distance: 0 }
  • offsets object:
skiddingNumberDefines the overlay-layout component positioning side by side with the overlay-trigger.
distanceNumberDefines the distance between the overlay-layout and the overlay-trigger components in the UI. A positive number places the overlay-layout component farther, while a negative number lets it overlap the overlay-trigger.


In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles

Contributors ✨

This project follows the all-contributors specification. Contributions of any kind are welcome!

Did this page help you?