VTEX Header

Description

The VTEX Header app is a store component that represents a top fixed navigation bar, and is used by store theme.

📢 Disclaimer: Don't fork this project; use, contribute, or open issue with your feature request.

Release schedule

ReleaseStatusInitial ReleaseMaintenance LTS StartEnd-of-lifeStore Compatibility
2.xCurrent Release2018-11-082.x
1.xMaintenance LTS2018-09-182018-11-08March 20191.x

See our LTS policy for more information.

Table of Contents

Usage

This app uses our store builder with the blocks architecture. To know more about Store Builder click here..

We add the header as a block in our Store.

To configure or customize this app, you need to import it in your dependencies in manifest.json.

1
2
3
  dependencies: {
    "vtex.store-header": "2.x"
  }

Then, add header block into your app theme as we do in our Store theme app.

Now, select the desired blocks, for example:

1
2
3
4
5
6
7
8
9
10
11
"header.full": {
  "blocks": [
    "login",
    "minicart",
    "logo",
    "search-bar",
    "menu-link",
    "telemarketing",
    "category-menu"
  ]
}

Blocks API

When implementing apps as a block various inner blocks may be available. The following interface lists the available blocks within header and describes if they are required or optional.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
"header": {
  "allowed": [
    "minicart",
    "login",
    "menu-link",
    "category-menu",
    "search-bar",
    "theme"
  ],
  "required": [
    "telemarketing",
    "logo"
  ],
  "component": "index"
},

"header.full": {
  "allowed": [
    "menu-link",
    "theme"
  ],
  "required": [
    "telemarketing",
    "logo",
    "minicart",
    "login",
    "category-menu",
    "search-bar"
  ],
  "component": "index"
},
}

It's essential to remark that, the header has the default and full versions defined as blocks by header and header.full respectively.

The header.full has telemarketing, logo, minicart, login, category-menu and search-bar as required inner-blocks, meanwhile header only requires telemarketing and logo. The menu-link and theme blocks are optional in both versions.

Note that every header implementation must append all required blocks within its version. Similarly, each inner block has its own configurable structure. There is a link to its API in the next section.

Configuration

Through the Storefront, you can change the headers's behavior and interface. However, you also can make in your theme app, as Store theme does.

Prop nameTypeDescriptionDefault value
leanWhenStringCases in which the menu is in lean mode'a^'
linkUrlStringAddress opened when the user clicks the logo'/'
logoUrlStringURL of the logo imageN/A
logoTitleStringAlt text for the logoN/A
logoSizeObjectSizes of logo in desktop and mobiledesktop: { width: 132, height: 40 }, mobile: { width: 90, height: 40 }
showSearchBarBooleanSets whether the search bar is visible or nottrue
showLoginBooleanSets whether the login button is displayed or nottrue
iconClassesStringClasses for icons'c-on-base'
labelClassesStringClasses for labels'c-on-base'
collapsibleAnimationObjectCollapsible animation controllingCollapsible Animation
Collapsible Animation

The Collapsible content can display animations on page scroll up or down, that can be configured through collapsibleAnimation, which is an object with the properties:

Prop nameTypeDescriptionDefault value
onScrollBooleanIf should animate on scrolltrue
alwaysBooleanIf should animate on every scroll up or downtrue
anchorNumberScroll value that animation starts to be active100
fromNumberInitial height before animation64
toNumberTarget height after animation0
presetStringAnimation configuration preset: more @ react-spring'default'
configObjectAnimation configuration: more @ react-spring{}

Also, you can configure the blocks telemarketing, logo, login, category-menu, search-bar and menu-link defined on header.

Styles API

This app provides some CSS classes as an API for style customization.

To use this CSS API, you must add the styles builder and create an app styling CSS file.

  1. Add the styles builder to your manifest.json:
1
2
3
  "builders": {
    "styles": "1.x"
  }
  1. Create a file called vtex.header.css inside the styles/css folder. Add your custom styles:
1
2
3
.container {
  margin-top: 10px;
}

CSS namespaces

Below, we describe the namespaces that are defined in the header.

Class nameDescriptionComponent Source
containerThe main container of headerindex
leanModeThe main container of header on lean modeindex
topMenuContainerThe container of fixed top menuFixedContent
topMenuLogoThe container of logo in fixed top menuLogo
topMenuSearchBarThe container of search bar in fixed top menuSearchBar
topMenuIconsThe container of icons on fixed top menuIcons
topMenuCollapsibleThe container of collapsible top menuCollapsible

Troubleshooting

You can check if others are passing through similar issues here. Also feel free to open issues or contribute with pull requests.

Contributing

Check it out how to contribute with this project.

Tests

To execute our tests go to react/ folder and run yarn test

Travis CI

Build Status
Coverage Status