@financial-times/o-header-services
v5.5.4
Published
Responsive page header for sites with minimal or customised branding, including internal products, customer facing tools, and specialist titles.
Downloads
1,901
Readme
o-header-services
This header is for tools and services built by the Financial Times.
Usage
Check out how to include Origami components in your project to get started with o-header-services
.
Markup
An o-header-services
header is divided into three main parts: title section (required), primary navigation (optional), and secondary navigation (optional). Each section is placed within a header
element:
<header class='o-header-services' data-o-component='o-header-services'>
<!-- Markup specific to the needs of your product. Options detailed below. -->
</header>
Title Section
A title section is required for every header, and every title section must include a logo and a product title.
The logo will default to the FT logo—if you are not using the build service you can customise it with the oHeaderServices()
Sass mixin.
You can choose to include a product tagline to describe your product concisely, and there is space for extra content such as a 'Sign In' link in this section of the header, too.
Note: If there is a 'Sign in' option, it should be consistent with other FT products by aligning itself to the right and avoiding different wording such as 'Log in' or 'Login'.
For an example and markup, see the title-only header in the Origami Registry.
Primary Navigation
The primary navigation is an optional addition to the title section. It's most useful for high-level navigation.
This section of the header has specific behaviour, as it turns into a drawer at smaller viewport sizes (740px down). It requires the addition an extra element in the title section to support the hamburger button.
If you are using extra content (such as a 'Sign in' link), that will be pulled into the drawer, as well. (This behaviour can be supressed by adding the class .o-header-services__related-content--always-visible
)
For an example and markup, see the primary navigation in the Origami Registry.
Core Experience Of The Drawer
Small screen users should still be able to access the contents of the drawer even if their browser doesn't cut the mustard or the JavaScript has failed to load. In this case we recommend you have the contents of the drawer at the bottom of the page in a footer that is only visible if the body has a .core
class. In core experience the hamburger menu links to an anchor at the bottom of the page.
Primary Navigation With Drop Down
The primary navigation can also handle dropdown menus. These menus are hidden behind a button that lives beside the navigation item that it is pertinent to.
Drop down menus also get pulled into the drawer on smaller viewports.
For an example and markup, see the primary navigation with drop downs in the Origami Registry.
If copying markup from the above example, update the following attributes of dropdown navigation items:
aria-label
: include the title of your navigation item in the label for your dropdown button.aria-controls
: link your dropdown button to theid
of theul
navigation list which it controls
The following example shows the correct markup for a "Documentation" dropdown:
<li data-o-header-services-level="1">
<a href>Documentation</a><!--
--><button
class="o-header-services__drop-down-button"
aria-controls="documentation-dropdown"
aria-label="Toggle documentation dropdown menu">
</button>
<ul
id="documentation-dropdown"
data-o-header-services-level="2"
aria-hidden="true">
<!-- dropdown navigation list items -->
</ul>
</li>
Secondary Navigation
The secondary navigation is also an optional addition to the header, but it makes more sense alongside the primary navigation, as it serves more complicated products.
It includes two sections of navigation: 'ancestors' and 'children'. The 'ancestor' section works in the form of a breadcrumb, and the children are relative to the ancestor.
At smaller viewports, it does not collapse into the drawer, but becomes scrollable instead.
For an example and markup, see the secondary navigation in the Origami Registry.
Themes
o-header-services
offers theming for B2B or B2C products for FT.com products who use the core brand. They are designed to affect the title section and the primary navigation.
To add a theme to the header, add the appropriate class to the header element. For example, for B2B that would be:
+<header class='o-header-services o-header-services--b2b' data-o-component='o-header'>
-<header class='o-header-services' data-o-component='o-header'>
<!-- Your header markup -->
</header>
For an example and markup, see the B2B and B2C headers in the Origami Registry.
Bleed Header
If your application requires a bleed header, you'll need to add the o-header-services--bleed
variant to your header.
+<header class='o-header-services o-header-services--bleed' data-o-component='o-header'>
-<header class='o-header-services' data-o-component='o-header'>
<!-- Your header markup -->
</header>
Sass
In order to output every type of o-header-services
style, you'll need to include the following:
@import '@financial-times/o-header-services/main';
@include oHeaderServices();
You can be more selective about which types you would like to output, by using an $opts
map. It accepts the following options:
types
'primary-nav'
'secondary-nav'
'bleed'
'b2b'
'b2c'
logo
- The logo image to show in the header. The image must come from an Origami image set. Specify the image set and image name as a string
[imageset]:[image]
e.gftlogo-v1:origami
. Defaults to the FT logo.
drawer-breakpoint
- The breakpoint to move the primary navigation into a drawer. We recommend a
rem
value or a layout size from o-grid e.g. 'M'. Defaults to the medium grid size 'M'.
To use a logo that is not the FT logo, the logo can be modified in one of two ways:
- By using a logo name from the logo image set (e.g. 'origami')
- By passing in a full url or data url that points at the SVG you want to use as a logo (e.g.
'https://www.example.com/logo.svg'
). Bear in mind that you can also run your chosen SVG through the Image Service's URL Builder, which will optimise the image and provide a URL for it.
In this example we include only the styles for a primary navigation with the bleed modifier. We opt to use the Origami logo from the logo image set.
@import '@financial-times/o-header-services/main';
@include oHeaderServices($opts: (
'types': ('primary-nav', 'bleed');
'logo': 'origami'
));
// Will output styles for a bleed header with a primary navigation and the Origami logo
Customisation
o-header-services
provides the option to customise the whitelabel
brand. If you are using this brand, you can modify brand-specific variables by overriding them in a map in oHeaderServicesCustomize
.
$o-brand: whitelabel;
@import '@financial-times/o-header-services/main';
@include oHeaderServicesCustomize((
'nav-hover-background': hotpink // will apply to background colors on hover, where appropriate
))
@include oHeaderServices($opts: (
'types': ('primary-nav'),
'features': ('drop-down')
));
We recommend customising the following brand variables:
- top-text
- top-background
- nav-text
- nav-background
- nav-border
- nav-hover-background
- nav-underline-color
- arrow-icon-color
- arrow-icon-hover-color
- button-hover-color
In addition, the following brand variables may also be customised:
- text-hover-color
- drawer-background
- drawer-button-background
- drawer-text-hover-color
- drawer-nav-hover-background
- primary-nav-item-horizontal-padding
JavaScript
No code will run automatically unless you are using the Build Service. You must either construct an o-header-services
object or fire an o.DOMContentLoaded
event, which o-header-services
listens for.
You'll need to set up your header declaratively, as the JavaScript for o-header-services
does not construct it for you.
The JavaScript is responsible for generating the drawer and enabling scrolling on the secondary navigation. You can implement that with the following:
import oHeaderServices from '@financial-times/o-header-services';
oHeaderServices.init();
Migration guide
State | Major Version | Last Minor Release | Migration guide | :---: | :---: | :---: | :---: ✨ active | 5 | N/A | migrate to v5 | ⚠ maintained | 4 | 4.0 | migrate to v4 | ╳ deprecated | 3 | 3.3 | migrate to v3 | ╳ deprecated | 2 | 2.3 | migrate to v2 | ╳ deprecated | 1 | 1.2 | N/A |
Contact
If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.
Licence
This software is published by the Financial Times under the MIT licence.