Navigation
Global navigation
Vanilla includes a simple navigation bar that you can add to the top of your sites.
The navigation items are collapsed behind a "Menu" link in small screens and displayed horizontally on larger screens.
Note:By default, the width of the navigation is constrained to $grid-max-width
. To make the navigation full width, replace .p-navigation__row
with .p-navigation__row--full-width
.
The navigation pattern is one of the first patterns to implement the new theming architecture in Vanilla. The default is light. But, to switch to a dark navigation, you can either:
- Override the value of the
$theme-default-nav
in_settings_themes.scss
todark
- Add a state class to the
p-navigation
class:is-dark
when the default navigation is light, oris-light
when the default has been changed to dark
You can also manually override the background color of the navigation using the variable $color-navigation-background
. If the lightness of the background is above 70%, the text colour will switch to dark to improve readability.
You can change the breakpoint at which the menu changes to a small screen menu
by adjusting the $breakpoint-navigation-threshold
in _settings_breakpoints.scss
.
Deprecated
In Vanilla 2.8 we deprecated the use of p-navigation__links
, p-navigation__link
and classless <a>
in the navigation. Support for these classes will be removed in future version 3.0.
You should use p-navigation__items
, p-navigation__item
and <a class="p-navigation__link">
instead.
To update to new class names:
- rename all occurrences of
p-navigation__links
top-navigation__items
- rename all occurrences of
p-navigation__link
top-navigation__item
- add
p-navigation__link
class to all<a>
elements that are direct child ofp-navigation__item
Sub-navigation
Sub-navigation drop-down menus can be added to the navigation by including one
or more p-subnav
components.
To open the subnav-menu you need to set the is-active
class on p-subnav
element, but also set aria-hidden
to false
on p-subnav__items
.
By default the sub-navigation menus are left-aligned with their parent, if you'd prefer the menu to be positioned from the right, use the p-subnav__items--right
modifier. This can be seen in the "My account" menu in the example.
Side navigation
The side navigation pattern can be used to provide more detailed navigation alongside your content.
It allows grouping the links into navigation sections and nesting them up to three levels.
Current page in the side navigation should be highlighted by adding aria-current="page"
attribute to the corresponding p-side-navigation__link
element. Alternatively, if aria-current
attribute cannot be set, the is-active
class can be used instead.
Use p-side-navigation__status
inside p-side-navigation__link
elements to add status labels or icons on right side of navigation items.
Icons
To add icons on the left side of the items in side navigation use the .p-side-navigation--items
class.
Note:Icons should only be used on the items in the first level of side navigation.
Sticky
On pages with content significantly longer than the side navigation contents you can make the navigation sticky to keep it visible when scrolling by adding .is-sticky
class to the root element of .p-side-navigation
.
Breaking change:Side navigation used to be sticky by default, but since Vanilla 2.21.0 .is-sticky
class is needed to add this functionality.
Raw HTML
When the HTML markup of the side navigation links is generated by an external service and Vanilla class names cannot be added to the elements, use the p-side-navigation--raw-html
modifier.
In this variant, the side navigation pattern will style headings (h2
, h3
, etc.) and lists (ul
, li
) with links or text elements (a
, strong
, span
) consistently with default side navigation component:
- headings (
h2
,h3
, etc.) get the styling ofp-side-navigation__item--title
- lists:
ul
tags are styled asp-side-navigation__list
, andli
tags asp-side-navigation__item
- nesting lists (
ul > li > ul > li ...
) is possible up to 3 levels
- nesting lists (
- text elements (
span
,strong
) insideli
are styled asp-side-navigation__text
- links (
a
) insideli
are styled asp-side-navigation__link
is-active
class needs to be added to a link element to mark the active page
Because of the limitations of raw HTML markup without class names, it's not possible to use icons or status labels in the raw HTML variant of side navigation.
Do:Use the raw HTML variant when the backend serving the navigation content won't allow custom class names on HTML elements.
Don't:Use raw HTML variant when the markup can be fully controlled and class names can be properly added to all elements.
JavaScript functionality
On small screens side navigation is rendered off-screen as a drawer. To open the side navigation drawer, add is-expanded
class to
main .p-side-navigation
element. To close the drawer (with the animation) remove is-expanded
class and replace it with is-collapsed
class.
To make sure side navigation toggle works without JavaScript the toggle button for opening the side navigation drawer should be an anchor with href
attribute pointing to the id
attribute of the side navigation element (for example: <a href="#drawer" class="p-side-navigation__toggle">
).
Application layout
For applications built with the application layout the size and positioning of the navigation panel is handled by the layout itself, so the side navigation component doesn't need it's own drawer, overlay or toggle buttons.
To use side navigation in the application place .p-side-navigation--icons
in the l-navigation
element. You don't use p-side-navigation__toggle
, p-side-navigation__overlay
or p-side-navigation__drawer
elements, just put the lists of the links p-side-navigation__list
as direct children of .p-side-navigation
element.
Additionally, in order for application layout to fully control side navigation elements when expanding and collapsing you need to wrap the text of the side navigation items in <span class="p-side-navigation__label">
. This will allow to fade them out when navigation collapses.
For more information, read the dedicated application layout documentation.
Theming
The side navigation is available in a light and a dark theme. The colours used by both themes in the colour settings file. Overriding the colours of individual elements of the side navigation is discouraged, as this may lead to accessibility issues, or inconsistencies with other components that use the same theme.
By default, the side navigation uses the light theme. To change the global default, set $theme-default-p-side-navigation
to dark
.
To change the appearance of an individual instance of the side navigation, you can use the is-dark
class.
For more details about themes in Vanilla refer to the Color theming section of the documentation.
See example of side navigation with dark theme.
Import
To import just navigation or sub-navigation component into your project, copy snippets below and include it in your main Sass file.
@import 'patterns_navigation';
@include vf-p-navigation;
// sub-navigation is optional you can include it alongside navigation component
@import 'patterns_subnav';
@include vf-p-subnav;
To import side navigation, copy snippet below:
@import 'patterns_side-navigation';
@include vf-p-side-navigation;
// optionally add icons and/or labels if you use them in side navigation__nav
@import 'patterns_label';
@include vf-p-label;
@import 'patterns_icons';
@include vf-p-icons;
For more information see Customising Vanilla in your projects, which includes overrides and importing instructions.
Design
For more information view the navigation and sub-navigation design spec, which includes the specification in markdown format and a PNG image.