Origami Frontend Components & Services

Readme: o-hierarchical-nav

Responsive hierarchical navigation pattern.

All navigation options have the same general markup structure that you can see in main.mustache.

Each navigation item can be either:

…and can have one of the following behaviours:

Where a navigation item is both a link and a parent or controller for mega-dropdown, the default behaviour on click will be cancelled.

Parent of sub-level

The <li> should be given a class of o-hierarchical-nav__parent, and should contain another <ul> list that declares its level via a data attribute:

<li class="o-hierarchical-nav__parent"><a>Level 2 item with sub-level</a>
    <ul data-o-hierarchical-nav-level="3">
        <li><a>Level 3 item</a></li>
        <li><a>Level 3 item</a></li>
    </ul>
</li>

When the nav item is clicked, the <li> will have an aria-expanded attribute toggled, which will control the visibility of the child list.

Controller for DOM element

The <li> should be given an aria-controls attribute with the value being the ID of the DOM element to control, for example:

<li aria-controls="megadropdown"><a>Mega dropdown</a></li>

...

<div id="megadropdown" aria-hidden="true">
    Mega-dropdown content
</div>

When the nav item is clicked, the element targeted by the aria-control attribute will have its aria-hidden attribute toggled.

Megadropdowns

The horizontal base style comes with default styling for a megadropdown element. This element has to add the class .o-hierarchical-nav__mega-dropdown.

Responsive collapsing of horizontal navigation

Horizontal navigation styles use o-squishy-list to allow priorities to be set on the top level nav items:

<nav>
    <ul data-o-hierarchical-nav-level="1">
        <li data-priority="2"><a>Important page</a></li>
        <li data-priority="3"><a>Less important page</a></li>
        <li data-priority="1"><a>Home</a></li>
    </ul>
</nav>

o-squishy-list will show as many items has will fit in the available width. If not everything will fit, then the necessary number of items will be hidden, starting with the lowest priority items.

If you don't want to use a responsive horizontal navigation, you can require Nav.js directly.

Hidden navigation items

A 'More' item may be added to the top level which will be populated with a list of elements that have been hidden by o-squishy-list:

<li data-more class="o-hierarchical-nav__parent" aria-hidden="true"><a>More</a></li>

This item is be hidden until it's needed. It's recommended that aria-hidden="true" should be added to a 'More' item so that it won't appear when running on core experience.

If there's a chance that all nav items will be hidden and added to the More list, then it's possible to change the text title of the More item depending on whether it contains some or all the navigation items:

<li data-more class="o-hierarchical-nav__parent"><a><span class="nav__more--if-some">More</span><span class="nav__more--if-all">Menu</span></a></li>

Sub-Components

If there is a structure required for the styling of nav components (i.e. other elements are required for icon display) or elements that are not links but should reduce to a sub-level when screen space does not allow then you can add a 'data-o-hierarchical-nav-is-cloneable' attribute and the element will be deeply cloned rather than a new anchor tag with the text content copied.

<li data-o-hierarchical-nav-is-cloneable><a><span>An item to clone</span><img src="" alt="icon"></a></li>

Vertical hierarchical nav

To make a nav work in a vertical layout, add data-o-hierarchical-nav-orientiation="vertical" to the <nav>.

Arrows

Add a <i></i> to display an arrow icon at the end of an <a> element:

<li class="o-hierarchical-nav__parent"><a>Item 3.2 (parent) <i></i></a>

Styling

There are two base mixins for modules and products to include:

Things that are important to add to your theme are:

If you want to style megadropdowns, you need to add @at-root before the .o-hierarchical-nav__mega-dropdown class.

JavaScript instantiation

Manual instantiation

An o-hierarchical-nav object must be constructed for every <nav> you have on your page that uses this module.

var oHierarchicalNav = require('o-hierarchical-nav');
var nav = document.querySelector('.o-hierarchical-nav');
var hierarchicalNav = new oHierarchicalNav(nav);

Auto-instantiation

Alternatively, a o.DOMContentLoaded event can be dispatched on the document to auto-construct a o-hierarchical-nav object for each element with a data-o-component="o-hierarchical-nav" attribute:

require('o-hierarchical-nav');

document.addEventListener("DOMContentLoaded", function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Migration Guide

Updating from v4 to v5

V4 -> V5 introduces the new major of o-colors. Updating to this new version will mean updating any other components that you have which are using o-colors. There are no other breaking changes in this release.


License

This software is published under the MIT licence.

Switch component view

GitHub Repository

Install o-hierarchical-nav

If using the Build Service, add o-hierarchical-nav@^5.0.6 to your script and link tags.

If running a Manual Build, run bower install --save "o-hierarchical-nav@^5.0.6".

Help & Support

o-hierarchical-nav is maintained directly by the Origami team. If you have any questions about o-hierarchical-nav or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com