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

Header

The VTEX 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.

header

Configuration

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

The Header is comprised of 3 others blocks: the header-layout, that in practice subdivides in two (header-layout.desktop and header-layout.mobile), the header-row and the header-border.

  1. First off, 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"
]
},
  1. Configure both header-layout.desktop and header-layout.mobile, declaring header-row to create Header lines according to your store needs.

In the example below, we will configure 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.

{
"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"
]
},

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 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're configured 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

⚠️ You should repeat step 4 for all header-layout.desktop header-rows, as well as redo steps 3 and 4 to define your header-layout.mobile.

You can add two more blocks to the header-row: header-border 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-spacer:

The header-spacer is tasked with adding spacing between blocks throughout the Header lines.

"header-row#3-desktop": {
"children": [
"vtex.menu@2.x:menu#websites",
"header-spacer",
"vtex.menu@2.x:menu#institutional"
],
"props": {
"blockClass": "menu-link",
"inverted": "true"
}
},

In practice, it will make blocks declared before it position themselves to the left on the screen, whereas blocks that are declared after will be positioned to the right. For example:

header-spacer

⚠️ The Header must be declared in blocks.jsonc just once, meaning that when you declare and configure the block in the homepage template, as mentioned in the configuration above, Store Framework will reproduce these same configurations for the remaining store templates behind the scenes. If you want to apply different configurations to the template, check the advanced configurations section below.

Advanced configuration

Automatic behind the scenes Header and Footer reproduction in other templates aside from store.home is only possible because both blocks are 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 and Footer blocks, declared just once in blocks.jsonc, as defaults 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 |