VTEX Developer Portal

The Header app is responsible for displaying a navigation bar fixed on a store's page upper side.
Other blocks that are important for user navigation are found in the Header, for example the store's logo, the minicart, user login and search bar.

headerheader

Configuration

  1. Add the store-header app to your theme's dependencies in manifest.json:
  dependencies: {
    "vtex.store-header": "2.x"
  }

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

Block nameDescription
header-layout.desktophttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Defines the Header layout for desktop device through header-row blocks.
header-layout.mobileDefines the Header layout for mobile device through header-row blocks.
header-rowhttps://img.shields.io/badge/-Mandatory-redhttps://img.shields.io/badge/-Mandatory-red Create Header lines according to your store needs.
header-borderAdds a 1px margin to a Header row.
header-force-centerCentralizes its children blocks in a Header row.
header-spacerAdds spacing between blocks throughout a Header row.
  1. Declare the two header-layout blocks, allowing you to define how the Header should be displayed for both mobile and desktop:
{
  "header": {
    "blocks": [
      "header-layout.desktop",
      "header-layout.mobile"
    ]
  },

:information_source: The Header does not need to be declared in a specific template of your theme, once the app is defined as default store interface element in the interfaces.json file. This means that Store Framework will reproduce the configurations defined in the file you just created for all store templates behind the scenes. If you want to apply different configurations to each store template, check the advanced configurations section below.

  1. Configure both header-layout.desktop and header-layout.mobile, declaring header-row to create Header lines according to your store needs.
{
  "header": {
    "blocks": [
      "header-layout.desktop",
      "header-layout.mobile"
    ]
  },
  "header-layout.desktop": {
    "children": [
      "header-row#1-desktop",
      "header-row#2-desktop",
      "header-row#3-desktop",
      "header-row#4-desktop"
    ]
  },

:warning: In the example above, we configured 4 different levels for header-layout.desktop. It will thus be possible to replicate the Header displayed above sheltering the telemarketing functionalities (when activated), a notification, links to pages and every other blocks, such as Logo, Menu, etc. Remember that the number of header-rows should meet your business needs, determining how many Header lines you want to apply to your store.

  1. Configure each of the header-rows , applying props and declaring the desired store blocks for each line. To correctly structure your Header, you should check the documentation for each of the desired blocks. The most commonly used are Logo, Minicart and Menu. In the example below, we will configure the header-row#1-desktop as Telemarketing:
"header-row#1-desktop": {
  "children": [
    "telemarketing"
  ],
  "props": {
    "fullWidth": true
  }
},
  • header-row props:
Prop nameTypeDescriptionDefault value
zIndexNumberCSS property that controls the vertical stacking order of elements for overlapping.0
stickyBooleanWhether the Header margin should be fixed on the layout (true) or not (false)false
fullWidthBooleanWhether the Header should take the full width of the screen or nottrue
invertedBooleanWhether the row will use the base color (false) or the inverted base color (true) as defined in styles.json.false

:warning: *Repeat step 4 for any other header-rows you may have in the header-layout.desktop. Remember to declare the desired blocks for each row, as we declared the Telemarketing block for the header-row#1-desktop, and properly configure all blocks using props. Once it is all finished, redo steps 3 and 4 to define your header-layout.mobile as well*.

Three blocks can be added as header-row's children in order to customize your Header row layout: header-border, header-force-center and header-spacer.

  • header-border:

When declared, the header-border block adds a 1px margin to your store's Header.

"header-row#2-desktop": {
  "children": [
    "header-border",
    "notification.bar#home"
  ],
  "props": {
    "fullWidth": "true"
  }
},
"notification.bar#home": {
  "props": {
    "content": "SELECTED ITEMS ON SALE! CHECK IT OUT!"
  }
},
Prop nameTypeDescriptionDefault value
stickyBooleanWhether the Header margin should be fixed in the layout or notfalse
  • header-force-center

When passed on, the header-force-center centralizes its children blocks in a Header row, for example:

"header-row#4-desktop": {
  "props": {
    "blockClass": "main-header",
    "horizontalAlign": "center",
    "verticalAlign": "center",
    "preventHorizontalStretch": true,
    "preventVerticalStretch": true,
    "fullWidth": true
  },
  "children": ["header-force-center"]
},  
"header-force-center": {
  "children":[
    "logo#desktop"
  ]
},
"logo#desktop": {
  "props": {
    "title": "Logo",
    "href": "/",
    "url": "https://storecomponents.vteximg.com.br/arquivos/store-theme-logo.png",
    "width": "180"
  }
},

header-force-centerheader-force-center

  • header-spacer:

The header-spacer is tasked with adding spacing between blocks throughout the Header rows. For example:

"header-row#3-desktop": {
  "children": [
    "[email protected]:menu#websites",
    "header-spacer",
    "[email protected]:menu#institutional"
  ],
  "props": {
    "blockClass": "menu-link",
    "inverted": "true"
  }
},

In practice, it will make all blocks declared before it position themselves to the left on the screen, whereas blocks that are declared after will be positioned to the right. Considering that the Menus were properly declared and configured in the theme code, we would have the following:

header-spacerheader-spacer

Advanced configuration

Automatic behind the scenes Header reproduction in every store template is only possible because it is defined as default store interface elements in the interfaces.json file from Store Theme.

This definition in interfaces.json enables Store Framework to identify the Header block declared just once in a blocks.jsonc file and reproduce it as default for all other templates.

To overwrite this automatic duplication in interfaces.json and use new configurations in different templates, refer to the step-by-step of the following recipe: Customizing the Header and Footer.

Customization

In order to apply CSS customizations in these and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.
| CSS Handles |
---------------------- |
| container |
| leanMode |
| topMenuContainer |
| topMenuLogo |
| topMenuSearchBar |
| topMenuIcons |
| topMenuCollapsible |
| forceCenter |
| forceCenterInnerContainer |
| headerBorder |
| headerSpacer |
| headerStickyRow |
| headerRowContentContainer |

Contributors ✨

Thanks goes to these wonderful people (emoji key):

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

Updated about a month ago


Header


Suggested Edits are limited on API Reference Pages

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