Header

BetaAccessible

The Header component is located at the top of the page above the main body content. It provides a place for levels of primary navigation and site-wide actions.

A work in progress!
The Header components are a collection of new navigation components the HDS team is currently fine tuning. This means that these components are subject to change. We are open to feedback regarding how they work.

Usage

Example

Skip To Content
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View full header example in Storybook.

Principles

  • It is strongly recommended to always include the header component on every page in your service.
  • The Header component is a wrapper for the HDS header navigation components. This means you should put all the other header elements inside this component.
  • The only mandatory component inside the header is HeaderActionBar. Other components may be used if needed.
  • The inner components should always be in this order: Header.SkipLink, Header.UniversalBar, HeaderActionBar and HeaderNavigationBar.
  • Try to keep the order of actions (language select, search, log in) consistent in navigation. Do not change the default order without a good reason.
  • To better understand how the navigation elements work and how they should be combined, see also Navigation pattern.

Variations

Variations are presented in the same order that they should be declared in inside the Header component.

With skip link

Use the Header.SkipLink component to help keyboard-only users skip to the main content on a page.

  • Using the Header.SkipLink component is optional but we recommend using it if you have any other header components beside the ActionBar.
  • The Header.SkipLink supports aria-label prop which gives possibility to define more informative text for screen readers.
Skip To Content
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View minimal header example with skip link in Storybook.

With universal bar

Header.UniversalBar is aimed to provide easy access for frequently visited and useful links, e.g. feedback and news.

  • Using the Header.UniversalBar component is optional.
  • If the primary link information is provided, it should direct to the webpage of City of Helsinki. We recommend using it if your service is outside the hel.fi domain in order to provide a quick and easy access to the City of Helsinki web page.
  • Keep the link labels clear and concise. Prefer max 1-2 word long labels so the labels don't go to the next line on smaller screens. Avoid starting multiple link labels with the same word.
  • Under large sized screens (992px and down) the Header.UniversalBar is hidden and the contents are moved inside the the Header.ActionBar component's menu.
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled.. View full header example with universal bar in Storybook.

With action bar

Header.ActionBar is the section that makes your service recognizeable. It provides the logo, name of the service and language selection, search and login features when needed.

  • You should always include the Header.ActionBar component in your Header.
  • The component provides two different service name styles via the titleStyle prop: TitleStyleType.Normal, which is the default, and TitleStyleType.Bold. We recommend to have a maximum of 22 character (including spaces) for title name regardless of which style is used.
  • Under large sized screens (992px and down) the Header.ActionBar undergoes some visual changes:
    • The contents of Header.NavigationMenu and Header.UniversalBar, if you have provided either of them, will move inside Header.ActionBar's menu.
    • The Header.LanguageSelector moves under the ActionBar.
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View full featured header example with action bar in Storybook.

With language selector
A work in progress!
The Header.LanguageSelector component is subject to change, mainly regarding how the dropdown offering additional languages is going to look and work.

Header.LanguageSelector offers the languages for the whole service. It is recommended to offer full Finnish, Swedish and English versions. Other languages can be added based on the need and target audience of the service. Smaller subset of content can be separated from fully translated content.

  • Using the Header.LanguageSelector is optional.
  • The Header.LanguageSelector component doesn't offer localisation logic, it merely provides the UI for offering and changing languages. We trust HDS users have their own localisation libraries that they can integrate with our component.
  • The Header component has onDidChangeLanguage prop function, where user can define a callback function which gets the selected language key (value) as parameter.
  • See example for Header.LanguageSelector in Storybook.
  • Under large sized screens (992px and down) the Header.LanguageSelector moves under the Header.ActionBar.

Use the Header.LanguageSelector when

  • There are no reasons not to. This is the default and fulfills almost all needs and use cases.
  • Responsive mobile view is needed. There is no room for many options unless some are placed in a dropdown.
  • There are many selectable languages, some primary and some secondary. Primary languages are usually shown outside of the dropdown.

Header.SimpleLanguageOptions is an alternative to Header.LanguageSelector. Like its name suggests, it is very simple and has no ordering logic or a mobile version. It should not be used unless the Header.LanguageSelector is not suitable for your special scenario.

Use the Header.SimpleLanguageOptions when

  • All language options should be visible at all the times.
  • Language options should not change location in mobile views.
  • The ordering of the options must be fixed and even the sortLanguageOptions option of the Header.LanguageSelector does not help.

Note that you have to handle mobile views manually.

With HDS login

Header offers UI components to use with HDS Login. These components handle login and logout requests, connection errors, and pick user data for the user menu. The components do not work without HDS login context, but ActionBarItem and ActionBarButton components can be used to achieve the same results without HDS Login.

Header Login button

The Login button is a variant of ActionBarItem. It uses the fixedRightPosition prop to have special functionality for mobile breakpoints.

Clicking the button starts the login process. The component also indicates loading progress and handles errors.

Note: the Login button will not render anything if the user is logged in. It can be used without manually checking the user's login state.

Header User Menu button

The user menu button is also a variant of ActionBarItem. It also sets the fixedRightPosition to true.

The component button auto-fills the avatar and label properties from user data.

Any number of submenu items can be placed inside the component. The Header.LogoutSubmenuButton should be placed as the last item.

Note: The user menu button will not render anything if the user is not logged in. It can be used without manually checking the user's login state.

Header Logout Submenu button

Clicking the button starts the logout process and logs the user out. The component also indicates loading progress and handles errors.

The button must be placed inside an ActionBarItem. There is no Logout button that can be placed in the Header like the Login button

Learn more

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled.

With search
A work in progress!
The Header.Search component is still in design process! We are working on it and will provide a full-featured component later on.

The Header.Search component is to be used for whole site wide search. Currently HDS recommends putting the SearchIcon inside the Header.ActionBar, and making it open search in separate search page by pressing the search icon. This enables using all needed search functionalities. A code example can be found in the Code page.

Skip To Content
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled.

ActionBarItem and ActionBarButton
A work in progress!
The Header.ActionBarItem and Header.ActionBarButton components are subject to change.

The Header.ActionBarItem is a generic component for displaying icon buttons on the action bar accompanied with dropdowns. Header.ActionBarButton is a generic button component for displaying buttons without dropdowns.

  • Both Header.ActionBarItem and Header.ActionBarButton extend native button element's attributes.
  • The item can be positioned behind a dividing line, setting it apart from the rest of the items with the prop fixedRightPosition. This is mainly reserved for Header.Login.
  • From breakpoint M (≥ 768px) and down Header.ActionBarItem using the fixedRightPosition prop is hidden and the contents are moved inside the the Header.ActionBar component's menu alongside NavigationMenu.
  • It is higly recommended to have maximum 2 ActionBarItems that use this high priority position, to conserve mobile menu's usability.

ActionBarItems can

  • Have an icon and text, but not only an icon.
  • Have only text. The text is centered like on ActionBar language selection.

Note: If one item has icon, all should have an icon.

Any ActionBarItem with a functionality that opens a dropdown, must have an indication, or a variation that visually tells the user how to close it as well. (e.g. Menu and Close button, Chevron angle up and down). Read more in accessibility notes.

Helsingin kaupunkiHelsingin kaupunki
  • Ei uusia ilmoituksia

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View full header example with navigation menu in Storybook.

ActionBarSubItem and ActionBarSubItemGroup
A work in progress!
The Header.ActionBarSubItem and Header.ActionBarSubItemGroup components are subject to change.

Header.ActionBarSubItems are placed inside a Header.ActionBarItem. The component can have text and an icon before and/or after it. It can behave like a link or a button. It depends on the given props.

Note: If one subitem has an icon, all related subitems should have an icon.

The Header.ActionBarSubItemGroup renders its children as a list and forms a group for screen readers. Its children should be Header.ActionBarSubItems.

Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View full header example with navigation menu in Storybook.

With navigation menu

The Header.NavigationMenu enables users to navigate to different pages of the service. The navigation menu supports up to 3 levels of page hierarchy. For more information and recommendations, see also Navigation pattern..

  • The Header.NavigationMenu component should come after the Header.ActionBar component.
  • Keep navigation menu link labels clear and concise. Prefer max 1-2 word long labels. Avoid starting multiple menu link labels with the same word. See also our accessibility notes about navigation menu's hierarchy.
  • From breakpoint M (≥ 768px) and down the Header.NavigationMenu is hidden and the contents are moved inside the the Header.ActionBar component's menu.
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View full header example with navigation menu in Storybook.

Colour variations

Header offers two variations with different backgrounds - one with white and one with black (default) text elements. Use variation that achieves better contrast with the brand background colour of your choice. Header supports also custom theming. Read more at customisation page. When customising colours, refer to colour guidelines to ensure accessibility.

Helsingin kaupunkiHelsingin kaupunki
Helsingin kaupunkiHelsingin kaupunki
Helsingin kaupunkiHelsingin kaupunki

Note: Header is designed to be used full width at the top of the page above the main content. Preview here might not scale correctly and mobile navigation menu is disabled. View full header with custom theme example in Storybook or toggle the dark theme in full featured story.