VTEX Developer Portal

All ContributorsAll Contributors

The Modal Layout app provides blocks that can help you create modals in your store.

imageimage

Configuration

  1. Add the modal layout's app to your theme's dependencies in the manifest.json:
  "dependencies": {
+   "vtex.modal-layout": "0.x"
  }

Now, you are able to use all blocks exported by the modal-layout app. Check out the full list below:

Block nameDescription
modal-triggerhttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Defines how the Modal content will be triggered through its children blocks.
modal-layouthttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Defines how the Modal content will be rendered through its children blocks. You can declare as its children the blocks modal-header and modal-content, described below, in order to create a modal with header and footer.
modal-headerRenders a close button and the blocks listed as its children, building a modal header. Notice: it does not automatically render a header for your modal. Instead, you should create the modal header as you desire using this block's children list.
modal-contentDefines how the Modal content will be rendered through its children blocks. Preferably, this block should be used along with the modal-header in order to create a modal with header and footer.
modal-actionsLogical block only responsible for rendering its child blocks that, in turn, are responsible for rendering call-to-action buttons inside the modal, such as a confirmation button.
modal-actions.closeButton that closes the modal when clicked on. It is extremely useful in scenarios where your modal only has a form or a disclaimer box providing information for users.
  1. Add the modal-trigger block in any store template of your choosing. In the example below, it will be added to the Home page:
{
  "store.home": {
    "children": [
      "modal-trigger#example"
    ]
  },
  1. Declare the modal-trigger block using its prop and configuring children blocks for it. The modal-trigger's first children must be a block of your choosing to trigger the Modal content. Then, a sibling block called modal-layout will be needed to effectively define the Modal content through its child block list. For example:
{
  "store.home": {
    "children": [
      "modal-trigger#example"
    ]
  },
   "modal-trigger#example": {
    "children": [
      "rich-text#example",
      "modal-layout#example"
    ]
  },
  "rich-text#example": {
    "props": {
      "text": "Click me"
    }
  },
  "modal-layout#example": {
    "children": [
      "rich-text#modal-content"
    ]
  },
  "rich-text#modal-content": {
    "props": {
      "text": "Hello"
    }
  }
}

In the example above, the Rich Text block renders the Click me text that will trigger the Modal content when clicked on. The modal content, in turn, is defined by the modal-layout block. According to the example above, the Modal content triggered by the Click me Rich Text would be a Hello text.

modal-trigger props

Prop nameTypeDescriptionDefault value
triggerenumWhether the Modal content should be triggered by user click ( click), when the page is fully loaded (load) or when the page is fully loaded but the modal will appears just once per session (load-session).click
customPixelEventIdstringStore event ID responsible for triggering the modal-trigger block (hence triggering the opening of modal-layout blocks on the interface as well).undefined
customPixelEventNamestringStore event name responsible for triggering the modal-trigger block (hence triggering the opening of modal-layout blocks on the interface as well). Some examples are: 'addToCart' and 'removeFromCart' events. Notice that using this prop will make the associated modal-layout open in every event with the specified name if no customPixelEventId is specified.undefined

modal-layout props

Prop nameTypeDescriptionDefault value
scrollenumDefines how the modal should be scrolled by users. Possible values are: body (users can scroll the whole modal by normally scrolling the page) and content (users can scroll the modal content when hovering it).content
blockClassstringUnique block ID to be used in CSS customization.undefined
disableEscapeKeyDownbooleanWhether the modal should be closed when pressing the Esc key (true) or not (false).false
fullScreenbooleanWhether the modal should fill the whole screen (true) or not (false). This prop is responsive i.e. it adapts itself to the device's breakpoints.false
backdropenumWhether the modal will have a clickable backdrop (clickable) or no backdrop at all (none). This prop is responsive i.e. it adapts itself to the device's breakpoints.clickable
customPixelEventIdstringStore event ID responsible for triggering the modal-layout block (hence triggering the closing of modal-layout blocks on the interface as well).undefined
customPixelEventNamestringStore event name responsible for triggering the modal-layout block (hence triggering the closing of modal-layout blocks on the interface as well). Some examples are: 'addToCart' and 'removeFromCart' events. Notice that using this prop will make the associated modal-layout close in every event with the specified name if no customPixelEventId is specified.undefined

modal-header props

Prop nameTypeDescriptionDefault value
showCloseButtonbooleanWhether the close icon button should be rendered in the modal header (true) or not (false).true
iconCloseSizenumberSize (in pixels) of the close icon button in the modal header.32

modal-actions.close props

Prop nameTypeDescriptionDefault value
labelstringDefines the text to be rendered in the close button. This prop default value depends on the store's default language which is set according to the website's binding.Cancel, Cancelar, or Cancelar for stores whose default language is, respectively, English, Spanish or Portuguese.

Customization

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
modal
backdropContainer
backdrop
closeButtonContainer
closeButton
container
contentContainer
headerContainer
headerContent
paper
topRow
triggerContainer

Contributors ✨

Thanks goes to these wonderful people:

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

Updated about a month ago


Modal Layout


Suggested Edits are limited on API Reference Pages

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