Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@bbc/psammead-navigation

bbc689Apache-2.09.2.22

A navigation bar to use on index pages

bbc, navigation

readme

psammead-navigation - Known Vulnerabilities Dependency Status peerDependencies Status Storybook GitHub license npm version PRs Welcome

Description

The @bbc/psammead-navigation package is a set of two components, NavigationUl and NavigationLi. They use ul and li HTML elements respectively. The package also includes a Hamburger Menu and a Dropdown Navigation which are visible for breakpoints under 600px.

Exports

/dropdown - Adds a dropdown navigation with hamburger menu which is visible for breakpoints under 600px /scrollable - Makes the navigation to be scrollable under 600px.

Installation

npm install @bbc/psammead-navigation

Props

Argument Type Required Default Example
children node Yes N/A <ScrollableNavigation dir={dir}><NavigationUl><NavigationLi url="/" script={latin} active="true">Home</NavigationLi><NavigationLi url="/sport" script={latin}>{Sport}</NavigationLi></NavigationUl><ScrollableNavigation/>
dir string No 'ltr' 'rtl'
isOpen boolean No false true
ampOpenClass string No null 'open'
brandBackgroundColour string Yes N/A '#B80000'
brandForegroundColour string Yes N/A '#FDFDFD'
brandBorderColour string Yes N/A '#EAB3B3'
brandHighlightColour string YesNo N/A '#FFFFFF'
Argument Type Required Default Example
children node Yes N/A <NavigationLi url="/" script={latin} active="true">Home</NavigationLi><NavigationLi url="/sport" script={latin}>{Sport}</NavigationLi>
Argument Type Required Default Example
url string Yes N/A /sport
script object Yes N/A { canon: { groupA: { fontSize: '28', lineHeight: '32',}, groupB: { fontSize: '32', lineHeight: '36', }, groupD: { fontSize: '44', lineHeight: '48', }, }, trafalgar: { groupA: { fontSize: '20', lineHeight: '24', }, groupB: { fontSize: '24', lineHeight: '28', }, groupD: { fontSize: '32', lineHeight: '36', }, }, }
active boolean No false true
currentPageText string No null Current page
service string Yes N/A 'news'
dir string No 'ltr' 'rtl'
brandForegroundColour string Yes N/A '#FDFDFD'
brandBorderColour string Yes N/A '#EAB3B3'
brandHighlightColour string YesNo N/A '#FFFFFF'

ScrollableNavigation

Argument Type Required Default Example
children node Yes N/A <NavigationUl><NavigationLi url="/" script={latin} active="true">Home</NavigationLi><NavigationLi url="/sport" script={latin}>{Sport}</NavigationLi></NavigationUl>
dir string No 'ltr' 'rtl'
brandBackgroundColour string Yes N/A '#B80000'
brandHighlightColour string YesNo N/A '#FFFFFF'

CanonicalDropdown

Argument Type Required Default Example
children node Yes N/A <DropdownUl><DropdownLi script={latin} service='news' key='sport' url='/sport' active="false"> Sport </DropdownLi></DropdownUl>
isOpen bool Yes N/A false

AmpDropdown

Argument Type Required Default Example
children node Yes N/A <DropdownUl><DropdownLi script={latin} service='news' key='sport' url='/sport' active="false"> Sport </DropdownLi></DropdownUl>
Argument Type Required Default Example
children string Yes N/A 'Sport'
url string Yes N/A /sport
script object Yes N/A { canon: { groupA: { fontSize: '28', lineHeight: '32',}, groupB: { fontSize: '32', lineHeight: '36', }, groupD: { fontSize: '44', lineHeight: '48', }, }, trafalgar: { groupA: { fontSize: '20', lineHeight: '24', }, groupB: { fontSize: '24', lineHeight: '28', }, groupD: { fontSize: '32', lineHeight: '36', }, }, }
service string Yes N/A 'news'
active boolean No false true
currentPageText string No null Current page
dir string No ltr rtl

CanonicalMenuButton

Argument Type Required Default Example
announcedText string Yes N/A 'Menu'
onClick function Yes N/A () => { console.log("Handle onClick action"); }
isOpen bool Yes N/A false
dir string no 'ltr' 'rtl'
script object Yes N/A { canon: { groupA: { fontSize: '28', lineHeight: '32',}, groupB: { fontSize: '32', lineHeight: '36', }, groupD: { fontSize: '44', lineHeight: '48', }, }, trafalgar: { groupA: { fontSize: '20', lineHeight: '24', }, groupB: { fontSize: '24', lineHeight: '28', }, groupD: { fontSize: '32', lineHeight: '36', }, }, }

AmpMenuButton

Argument Type Required Default Example
announcedText string Yes N/A 'Menu'
onToggle string Yes N/A "menu.toggleVisibility" - must be an action on a valid AMP target
dir string no 'ltr' 'rtl'
script object Yes N/A { canon: { groupA: { fontSize: '28', lineHeight: '32',}, groupB: { fontSize: '32', lineHeight: '36', }, groupD: { fontSize: '44', lineHeight: '48', }, }, trafalgar: { groupA: { fontSize: '20', lineHeight: '24', }, groupB: { fontSize: '24', lineHeight: '28', }, groupD: { fontSize: '32', lineHeight: '36', }, }, }
import React from 'react';
import { ScrollableNavigation } from '@bbc/psammead-navigation/scrollable';
import Navigation, {
  NavigationUl,
  NavigationLi,
} from '@bbc/psammead-navigation';
import { latin } from '@bbc/gel-foundations/scripts';

<Navigation
  brandBackgroundColour='#B80000'
  brandForegroundColour='#FDFDFD'
  brandBorderColour='#EAB3B3'
  brandHighlightColour='#FFFFFF'
>
  <ScrollableNavigation
    brandBackgroundColour='#B80000'
    brandHighlightColour='#FFFFFF'
  >
    <NavigationUl>
      <NavigationLi
        url="/"
        script={latin}
        active
        currentPageText="Current Page"
        service="news"
        brandForegroundColour='#FDFDFD'
        brandBorderColour='#EAB3B3'
        brandHighlightColour='#FFFFFF'
      >
        Home
      </NavigationLi>
      <NavigationLi
        url="/sport"
        script={latin}
        service="news"
        brandForegroundColour='#FDFDFD'
        brandBorderColour='#EAB3B3'
        brandHighlightColour='#FFFFFF'
      >
        {Sport}
      </NavigationLi>
      <NavigationLi
        url="/weather"
        script={latin}
        service="news"
        brandForegroundColour='#FDFDFD'
        brandBorderColour='#EAB3B3'
        brandHighlightColour='#FFFFFF'
      >
        {Weather}
      </NavigationLi>
    </NavigationUl>
  </ScrollableNavigation>
</Navigation>;
import React from 'react';
import {
  Dropdown,
  DropdownUl,
  DropdownLi,
} from '@bbc/psammead-navigation/dropdown';
import { latin } from '@bbc/gel-foundations/scripts';

<CanonicalDropdown isOpen={isOpen}>
  <DropdownUl>
    <DropdownLi
      script={latin}
      service="news"
      key="Home"
      url="/"
      active
      currentPageText="Current page"
    >
      Home
    </DropdownLi>
    <DropdownLi script={latin} service="news" key="Sport" url="/sport">
      Sport
    </DropdownLi>
  </DropdownUl>
</CanonicalDropdown>

Canonical Menu Button Usage

import React from 'react';
import { CanonicalMenuButton } from '@bbc/psammead-navigation/dropdown';
import { latin } from '@bbc/gel-foundations/scripts';

<CanonicalMenuButton
  announcedText="Menu"
  isOpen
  dir={dir}
  onClick={() => {
    console.log('Handle onClick action');
  }}
  script={latin}
/>

Amp Menu Button Usage

import React from 'react';
import { AmpMenuButton } from '@bbc/psammead-navigation/dropdown';
import { latin } from '@bbc/gel-foundations/scripts';

<AmpMenuButton
  announcedText="Menu"
  onToggle="menu.toggleVisibility"
  script={latin}
  dir={dir}
/>

Note that in order for the AmpMenuButton toggling to work correctly, an id should be added to the Navigation component. This id can be passed in as a prop to the component. Similarly, ScrollableNavigation also requires an id to be added to it.

When to use this component

The Navigation is designed to show a navigation bar on all pages, which will show all sections on a site. If there are too many items to fit on one line, the items will wrap to the next lines.

On the other hand, with ScrollableNavigation we can make the list to remain on one line and to be horizontally scrollable to allow access to further links, under 600px.

Accessibility notes

The Navigation has a navigation landmark to provide a way to identify links that are intended to be used for navigation.

We have added the role list and listitem to the NavigationUl and NavigationList respectively, due to a VoiceOver bug to reinstate the list semantics.

We have also added visually hidden text to let the user know which item in both regular and dropdown Navigation is the current page. Note the use of visually hidden text here is due to lack of support at this time for the aria-current page attribute. Also note the use of role="text" to stop text splitting in VoiceOver.

We have added an aria-expanded attribute to the menu button to indicate whether the menu is collapsed or expanded.

Contributing

Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead respository.

Code of Conduct

We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.

License

Psammead is Apache 2.0 licensed.

changelog

Psammead Navigation Changelog

Version Description
9.2.22 PR#4636 Bumps from psammead-assets
9.2.21 PR#4634 Bumps psammead-assets
9.2.20 PR#4633 bump psammead-styles
9.2.19 PR#4632 psammead-styles bump
9.2.18 PR#4631 Adds English stories in storybook
9.2.17 PR#4609 Bump from psammead-styles
9.2.16 PR#4599 Fix TalkBack reading nested spans incorrectly, and reading ',' as 'comma' in Dropdown Navigation
9.2.15 PR#4601 Bumps dependencies
9.2.14 PR#4587 Fix TalkBack reading nested spans incorrectly
9.2.13 PR#4590 Fix talkback comma bug
9.2.12 PR#4574 Bumps psammead-styles
9.2.11 PR#4568 Bump dependencies
9.2.10 PR#4565 Bump from psammead-styles
9.2.9 PR#4562 Bump psammead-styles
9.2.8 PR#4561 Bump dependencies for @bbc/psammead-styles
9.2.7 PR#4534 Fixes prop warnings in storybook
9.2.6 PR#4548 Bumps dependencies
9.2.5 PR#4547 Bumps packages
9.2.4 PR#4545 Bump dependencies for @bbc/psammead-styles
9.2.3 PR#4552 Bump psammead-styles
9.2.2 PR#4497 Bump psammead-styles
9.2.1 PR#4486 upgrade minor/patch dependencies
9.2.0 PR#4475 Adds bottom nav border in high contrast mode
9.1.1 PR#4438 add data-e2e attribute for e2e tests
9.1.0 PR#4437 add data-e2e attribute for e2e tests
9.0.11 PR#4420 bumps 3rd-party dependencies
9.0.10 PR#4368 use Yarn Workspaces
9.0.9 PR#4335 switch to yarn for package management
9.0.8 PR#4304 Talos - Bump Dependencies - @bbc/gel-foundations, @bbc/psammead-assets, @bbc/psammead-styles, @bbc/psammead-visually-hidden-text
9.0.7 PR#4303 Trigger rebuild following babel config update for emotion 11
9.0.6 PR#4271 change react peer dep to >=16.9.0
9.0.5 PR#4266 Talos - Bump Dependencies - @bbc/psammead-assets, @bbc/psammead-visually-hidden-text
9.0.4 PR#4260 Talos - Bump Dependencies - @bbc/gel-foundations
9.0.3 PR#4256 Talos - Bump Dependencies - @bbc/psammead-styles
9.0.2 PR#4193 Upgrade Emotion to v11
9.0.1 PR#4226 Talos - Bump Dependencies - @bbc/psammead-styles
9.0.0 PR#4187 Require colours to be passed in as props
8.0.9 PR#4189 Talos - Bump Dependencies - @bbc/psammead-assets, @bbc/psammead-styles
8.0.8 PR#4087 Talos - Bump Dependencies - @bbc/psammead-assets
8.0.7 PR#4072 Talos - Bump Dependencies - @bbc/psammead-styles
8.0.6 PR#4052 Talos - Bump Dependencies - @bbc/gel-foundations
8.0.5 PR#4029 Talos - Bump Dependencies - @bbc/psammead-styles
8.0.4 PR#4010 Talos - Bump Dependencies - @bbc/psammead-assets
8.0.3 PR#3944 Talos - Bump Dependencies - @bbc/psammead-styles
8.0.2 PR#3927 Remove comment referencing styled-components.
8.0.1 PR#3925 Talos - Bump Dependencies - @bbc/psammead-assets, @bbc/psammead-styles, @bbc/psammead-visually-hidden-text
8.0.0 PR#3900 Migrate to Emotion.
7.0.3 PR#3883 Talos - Bump Dependencies - @bbc/psammead-assets, @bbc/psammead-styles, @bbc/psammead-visually-hidden-text
7.0.2 PR#3855 Talos - Bump Dependencies - @bbc/gel-foundations
7.0.1 PR#3854 Talos - Bump Dependencies - @bbc/psammead-styles
7.0.0-alpha.0 PR#3843 Bump Dependencies - @bbc/psammead-styles alpha version
6.0.23 PR#3836 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.22 PR#3816 Talos - Bump Dependencies
6.0.21 PR#3728 Tweaks following Storybook v5.3.19 to v6.0.22 update
6.0.20 PR#3811 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.19 PR#3785 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.18 PR#3772 Bump prettier to 2.1.2
6.0.17 PR#3710 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.16 PR#3707 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.15 PR#3628 Tweak :after styling to obscure pink bottom line
6.0.14 PR#3623 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.13 PR#3613 Talos - Bump Dependencies - @bbc/psammead-assets
6.0.12 PR#3604 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.11 PR#3467 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.10 PR#3427 Talos - Bump Dependencies - @bbc/visually-hidden-text
6.0.9 PR#3397 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.8 PR#3388 Update react-helmet to 6.0.0
6.0.7 PR#3381 Talos - Bump Dependencies - @bbc/psammead-assets
6.0.6 PR#3252 Remove scroll-behavior: smooth; from StyledScrollableNav
6.0.5 PR#3177 Add cursor: pointer to Menu button
6.0.4 PR#3135 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.3 PR#3129 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.2 PR#3059 Update gradient width on scrollable navigation
6.0.1 PR#3030 Talos - Bump Dependencies - @bbc/psammead-styles, @bbc/psammead-assets
6.0.0 PR#3028 Bring Navigation out of alpha
6.0.0-alpha.27 PR#2996 Talos - Bump Dependencies - @bbc/psammead-assets
6.0.0-alpha.26 PR#2990 Use GEL_SPACING_HLF and GEL_SPACING_SEXT constants
6.0.0-alpha.25 PR#2989 Talos - Bump Dependencies - @bbc/psammead-assets
6.0.0-alpha.24 PR#2978 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.0-alpha.23 PR#2973 Talos - Bump Dependencies - @bbc/psammead-styles
6.0.0-alpha.22 PR#2951 Use visually hidden text instead of aria label in nav button
6.0.0-alpha.21 PR#2923 Update padding between navigation items
6.0.0-alpha.20 PR#2920 Talos - Bump Dependencies - @bbc/gel-foundations
6.0.0-alpha.19 PR#2875 Remove aria-hidden from the scrollable navigation
6.0.0-alpha.18 PR#2847 Add animation to Dropdown Navigation
6.0.0-alpha.17 PR#2829 Remove references to SkipLink
6.0.0-alpha.16 PR#2827 Talos - Bump Dependencies - @bbc/psammead-assets
6.0.0-alpha.15 PR#2802 Spread extra Navigation props
6.0.0-alpha.14 PR#2810 Put amp background colour for nav css into a media query for mobile
6.0.0-alpha.13 PR#2801 Remove media query hooks and use props
6.0.0-alpha.12 PR#2799 Refactor Canonical MenuButton props
6.0.0-alpha.11 PR#2787 Update useMediaQuery hook to ensure server/client markup is consistent
6.0.0-alpha.10 PR#2785 Add id, ampOpenClass props to Navigation
6.0.0-alpha.9 PR#2779 Merge AMP tap handlers correctly
6.0.0-alpha.8 PR#2778 Fix menu border in FireFox high contrast mode
6.0.0-alpha.7 PR#2771 Spread the on prop (and others) onto the button, and set AMP Nav menu button initial state
6.0.0-alpha.6 PR#2769 Add isOpen prop to Navigation
6.0.0-alpha.5 PR#2759 Change size of menu button depending on script
6.0.0-alpha.4 PR#2747 Fix MenuButton not acting as a block element
6.0.0-alpha.3 PR#2745 Add dir prop to Amp and Canonical MenuButton
6.0.0-alpha.2 PR#2725 Move hooks directory into src
6.0.0-alpha.1 PR#2613 Add dropdown menu with a hamburger button
5.0.0-alpha.2 PR#2701 Talos - Bump Dependencies - @bbc/psammead-styles
5.0.0-alpha.1 PR#2577 Add scrollable navigation
4.0.0-alpha.2 PR#2697 Talos - Bump Dependencies - @bbc/psammead-styles
4.0.0-alpha.1 PR#2563 Remove skip to content link
3.1.0-alpha.1 PR#2567 Add C_WHITE top border to Navigation
3.0.5 PR#2519 Talos - Bump Dependencies - @bbc/psammead-styles
3.0.4 PR#2488 Talos - Bump Dependencies - @bbc/gel-foundations
3.0.3 PR#2477 Talos - Bump Dependencies - @bbc/psammead-styles
3.0.2 PR#2440 Talos - Bump Dependencies - @bbc/psammead-styles, @bbc/psammead-visually-hidden-text
3.0.1 PR#2404 replace inputProvider and dirDecorator with withServicesInput
3.0.0 PR#2377 Spread extra props to the component
2.3.6 PR#2343 Add data-navigation data attribute to navigation links
2.3.5 PR#2289 Talos - Bump Dependencies - @bbc/psammead-styles
2.3.4 PR#2273 Talos - Bump Dependencies - @bbc/psammead-styles
2.3.3 PR#2251 Talos - Bump Dependencies - @bbc/psammead-styles
2.3.2 PR#2191 Talos - Bump Dependencies - @bbc/gel-foundations
2.3.1 PR#2147 Add props for Storybook story withBrand.
2.3.0 PR#2117 Pass dir prop to Navigation component instead of NavigationLi
2.2.11 PR#2092 Refactored navigation component
2.2.12 PR#2145 Talos - Bump Dependencies - @bbc/psammead-styles
2.2.11 PR#1963 Refactored navigation component
2.2.10 PR#2081 Talos - Bump Dependencies - @bbc/psammead-styles, @bbc/psammead-visually-hidden-text
2.2.9 PR#1926 Update component storybook to use latest inputProvider changes
2.2.8 PR#1993 Talos - Bump Dependencies
2.2.7 PR#1960 Change <React.Fragment> to <>
2.2.6 PR#1942 Talos - Bump React to 16.9.0
2.2.5 PR#1938 Consistent use of destructuring props
2.2.4 PR#1931 Talos - Bump Dependencies
2.2.3 PR#1826 Talos - Bump Dependencies
2.2.2 PR#1804 Talos - Bump Dependencies
2.2.1 PR#1803 Patches broken links on badges in documentation
2.2.0 PR#1794 Add david dependency badges
2.1.5 PR#1734 Talos - Bump Dependencies
2.1.4 PR#1685 Bump dependencies
2.1.3 PR#1682 Move all dev dependencies to top level package.json
2.1.2 PR#1641 Bump dependencies
2.1.1 PR#1365 Bump psammead-styles to 1.2.0
2.1.0 PR#1233 Add ESM modules entry
2.0.1 PR#1182 Bump dependencies
2.0.0 PR#1027 Apply font based on service prop
1.0.6 PR#1082 Bump lodash security vulnerability
1.0.5 PR#1038 Bump dependencies
1.0.4 PR#892 Bump dependencies
1.0.3 PR#783 Update to latest psammead-test-helpers. Update snapshots.
1.0.2 PR#769 Fix stories not appearing in storybook when using install:packages:link
1.0.1 PR#713 Update styled-components to 4.3.2
1.0.0 PR#740 Remove alpha tag
1.0.0-alpha.1 PR#711 Update Navigation to have a max-width of 80rem.
1.0.0-alpha.0 PR#637 Create initial package with Navigation component.