https://github.com/nice-digital/global-nav
Global header and footer components for NICE digital services
https://github.com/nice-digital/global-nav
footer header nav navigation nervjs react webpack
Last synced: 11 months ago
JSON representation
Global header and footer components for NICE digital services
- Host: GitHub
- URL: https://github.com/nice-digital/global-nav
- Owner: nice-digital
- License: mit
- Created: 2019-01-29T09:34:27.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-04-01T14:17:13.000Z (about 1 year ago)
- Last Synced: 2025-06-30T10:07:05.843Z (11 months ago)
- Topics: footer, header, nav, navigation, nervjs, react, webpack
- Language: JavaScript
- Size: 3.83 MB
- Stars: 2
- Watchers: 3
- Forks: 1
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Global navigation
> Global header and footer used across all NICE digital services
[**:rocket: Jump straight to getting started**](#rocket-set-up)
[](https://github.com/nice-digital/global-nav)
[](https://github.com/nice-digital/global-nav/blob/master/LICENSE)
[](https://github.com/nice-digital/nice-design-system)
:bookmark_tabs: Table of contents (click to expand)
- [Global navigation](#global-navigation)
- [What is it?](#what-is-it)
- [Functionality](#functionality)
- [Non-functional](#non-functional)
- [Stack](#stack)
- [Principles](#principles)
- [CSS Modules](#css-modules)
- [:rocket: Set up](#rocket-set-up)
- [Other commands](#other-commands)
- [Tests](#tests)
- [Run individual files](#run-individual-files)
- [Run individual tests](#run-individual-tests)
- [Linting](#linting)
- [Production build](#production-build)
- [IDE](#ide)
- [Extensions](#extensions)
- [Gotchas](#gotchas)
- [How to use](#how-to-use)
- [React](#react)
- [Installation](#installation)
- [Usage](#usage)
- [Props](#props)
- [Main props](#main-props)
- [Main.withPadding](#mainwithpadding)
- [Header props](#header-props)
- [Header.service](#headerservice)
- [Header.skipLinkId](#headerskiplinkid)
- [Header.renderSearchOnly](#headerrendersearchonly)
- [Header.onNavigating](#headeronnavigating)
- [Header.onResize](#headeronresize)
- [Header.onDropdownOpen](#headerondropdownopen)
- [Header.onDropdownClose](#headerondropdownclose)
- [Header.additionalSubMenuItems](#headeradditionalsubmenuitems)
- [Header.search](#headersearch)
- [Header.search.url](#headersearchurl)
- [Header.search.autocomplete](#headersearchautocomplete)
- [Header.search.placeholder](#headersearchplaceholder)
- [Header.search.query](#headersearchquery)
- [Header.search.onSearching](#headersearchonsearching)
- [Header.auth](#headerauth)
- [Header.auth.environment](#headerauthenvironment)
- [Header.auth.provider](#headerauthprovider)
- [Header.auth.links](#headerauthlinks)
- [Header.auth.displayName](#headerauthdisplayname)
- [Footer props](#footer-props)
- [Footer.service](#footerservice)
- [CDN](#cdn)
- [Container IDs](#container-ids)
- [Overrides](#overrides)
- [Configuration](#configuration)
- [service](#service)
- [header](#header)
- [header.onRendering](#headeronrendering)
- [header.onRendered](#headeronrendered)
- [footer](#footer)
- [Deployments](#deployments)
- [Upgrading to v2](#upgrading-to-v2)
- [Upgrading to v3](#upgrading-to-v3)
- [Upgrading to v4](#upgrading-to-v4)
- [Upgrading to v5](#upgrading-to-v5)
- [Upgrading to v6](#upgrading-to-v6)
## What is it?
Global Nav consists common header and footer to be used across all NICE digital services. It is designed to be used across any NICE branded, externally facing web application. This includes all externally facing services that sit under the nice.org.uk domain. It also includes other NICE branded sites like Evidence Search that sit on non-NICE domains. It is a replacement for [NICE.TopHat](https://github.com/nice-digital/NICE.TopHat).
### Functionality
The header covers the following high-level functionality:
- main navigation
- skip links
- search and autocomplete
- COVID-19 message
- TLS warning message for old IE
- sign in and account management via NICE Accounts
- In the future will support Auth0
### Non-functional
The following non-functional requirements apply:
- _accessible_: to WCAG 2.0 AA
- _touch_: optimized for touch with sufficient touch targets
- _print_: print styles
- _security_: tested against OWASP top 10 and pen tested
- _progressive enhancement_:
- mobile first
- non-JS fallback for SSR React apps
- _browser support_: IE11+
## Stack
- [React](https://reactjs.org/)
- [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html) for styles
- [CSS Modules](https://github.com/css-modules/css-modules) for generated class names
- [PostCSS](https://postcss.org/) for transforming CSS with plugins:
- [autoprefixer](https://autoprefixer.github.io/) for automatically adding vendor prefixes in CSS
- and [NICE Digital shared browserslist config](https://github.com/nice-digital/browserslist-config#readme)
- [Vite](https://vitejs.dev/) for module bundling
- [Babel 7](https://babeljs.io/) for ES6/JSX → ES5 transpilation
- [accessible-autocomplete](https://github.com/alphagov/accessible-autocomplete)
- [ESLint](https://eslint.org/) for linting our JavaScript
- with [NICE Digital shared eslint config](https://www.npmjs.com/package/@nice-digital/eslint-config)
- [Stylelint](https://stylelint.io/) for linting our SCSS
- [Prettier](https://prettier.io/) for code formatting
- [Jest](https://jestjs.io/) for JS unit tests and snapshot tests
- [NICE Design System](https://nice-digital.github.io/nice-design-system/) core for SASS mixins, functions and colour/spacing variables
- [NICE Icons](https://github.com/nice-digital/nice-icons)
### Principles
Consider the following development principles:
- One single header and footer component (and optional main wrapper component with back to top link) across _all_ NICE services
- Progressively enhanced to support maximum number of devices and browsers
- Fast performance
- single HTTP request for CDN minified bundle
- as small as possible bundle size
- High unit test coverage
- 'Standard' React wherever possible
- easy for any React developer to pickup
- Consistent code style and formatting
- as if a single developer worked across the codebase
- Clear extension points and hooks for integrating into applications
- To avoid some of the issues from TopHat where there was no consistency
### CSS Modules
We use SCSS modules for a few reasons:
- local scoping of SCSS avoids accidental cascades:
- within global nav
- polluting out of global nav into the global scope
- obfuscated class names discourages overriding CSS styles in your app. This is by design to keep the header consistent across all services.
Using SCSS allows us to use mixins, functions and variables from the NICE Design System.
> If you _really_ need to override styles, see the [overrides documentation](#overrides).
## :rocket: Set up
**TL;DR;** to run the project locally, do the following:
- install [Node 14+](https://nodejs.org/en/download/) or latest LTS version. Or even better, use [Volta](https://volta.sh/) to use the Node version pinned in package.json.
- run `npm ci` on the command line to install dependencies
- run `npm start` on the command line
- navigate to http://localhost:8080/ in a browser.
This compiles the application and spins up a development server. It then watches for changes to files and:
- lints changed files
- automatically rebuilds the app.
It then automatically reloads the application in the Browser (so no need for a manual reload) using [Hot Module Replacement (HMR) in webpack](https://webpack.js.org/concepts/hot-module-replacement/).
### Other commands
There are various other commands you can run for further things like tests and linting:
#### Tests
- `npm test` Lints code and runs tests
- `npm test:unit` Runs Jest unit tests
- `npm test:unit:watch` Runs Jest unit tests and watches for changes. Run this in development.
- `npm test:unit:coverage` Runs Jest unit tests and reports coverage
If you've installed the [VSCode npm extension](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) then you can easily run scripts by:
- right-clicking the script name in _package.json_
- or _Ctrl+Shift+P_ -> _npm run script_ -> _test:unit:watch_.
##### Run individual files
To run a single test file, use the [jest cli option](https://jestjs.io/docs/en/cli.html#jest-regexfortestfiles) to pass in a regex to match test files. For example, to run just files that match _nav_:
```sh
npm run-script test:unit -- nav
```
##### Run individual tests
To run a single test, or a bunch of tests that match a given name, use the [jest `--testNamePattern` cli flag](https://jestjs.io/docs/en/cli.html#testnamepattern-regex) (or the `-t` alias). For example, to run all tests that check aria attributes:
```sh
npm run-script test:unit -- -t aria
```
#### Linting
- `npm run lint` Lints both JavaScript and SCSS
- `npm run prettier` Checks files for Prettier code style
- `npm run prettier:fix` Fixes Prettier code style issues
- `npm run lint:js` Lints just JavaScript files
- `npm run lint:js:fix` Fixes linting issues automatically in JavaScript files
- `npm run lint:scss` Lints just SCSS files
- `npm run lint:scss:fix` Fixes linting issues automatically in SCSS files
#### Production build
To distinguish between local development builds and builds on TeamCity, a custom npm script has been added, 'build:teamcity.'. The local build step does not work on TeamCity as 'vite build' needs to be passed differently for a build configuration step. For production on TeamCity, npm run build:teamcity is used first, then 'vite build' is passed in:
```bash
run build:teamcity vite build
```
### IDE
We recommend using VS Code as the IDE. It's free, used consistently across NICE Digital Services because of the .NET integration and is extensible with high quality, useful extensions:
#### Extensions
The following VS Code extensions are **strongly** recommended, but not required:
- [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - configures VSCode to use the correct settings (line endings etc) for various files
- [stylelint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint) - this will highlight SCSS linting errors directly in the IDE
- [eslint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint) - automatically lints your JavaScript as you type and highlights any errors
- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - highlights code formatting issues in the IDE and formats the file on save
- [npm](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) and [npm Intellisense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense) for support for using npm
- [Jest](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest) for automatically running tests and highlighting errors in the IDE
### Gotchas
- Check you have the right version of Node installed
- Make sure have LF line endings as this is a cross-platform project. This _should_ happen automatically because of settings in _.gitattributes_ and _.editorconfig_.
- Watch out for features of React that Nerv doesn't support, for example refs.
## How to use
We support 2 main methods for using the Global Nav in your projects:
- as a [React component](#react) installed directly into your app
- or externally to your app, loaded via the [CDN](#cdn).
### React
Install and use Global Nav as a dependency in a React application to include it as part of your application bundle.
This is a good option if you're rendering you're app's interface via React, either client side or server side, or both. For example, if you're using [Create React App](https://facebook.github.io/create-react-app/), [Gatsby](https://www.gatsbyjs.org/) or [Next.js](https://nextjs.org/).
> Note if you're using Create React App you'll need to use v2+ because we use CSS modules
Install the package and require the `Header`, `Footer` and `Main` React components into your application, just as you would for any other 3rd party component:
#### Installation
First, install the _@nice-digital/global-nav_ package [from npm](https://www.npmjs.com/package/@nice-digital/global-nav) into your project:
```sh
npm i @nice-digital/global-nav --save
```
> Note: we used to recommend installing directly from GitHub via `npm i nice-digital/global-nav --save` (notice the missing _@_), which still works but we now recommend using npm.
Then, require the header and/or footer and/or main into your application:
#### Usage
Import the header, footer and main component like this:
```js
import { Header, Footer, Main } from '@nice-digital/global-nav';
```
> Note: we've used ES6 module imports for this examples as we've assumed all React apps will be using ES6.
These header, footer and main components that can be be used like any other React component and configured via [props](#props), for example:
```jsx
const search = {
autocomplete: '/autocomplete',
};
const page = () => (
{/* Your page content here */}
);
```
Wrapping your template with the main component will render a main tag in the html with a back to top link.
For a full list of all the available props, see the [props section](#props) below:
#### Props
##### Main props
###### Main.withPadding
- Type: `Boolean`
- Default: true
Optional spacing between page content and footer back-to-top link.
##### Header props
###### Header.service
- Type: `String | null`
- Default: `''`
- Values: `guidance`, `standards`, `evidence`, `bnf`, `bnfc`, `cks`, `journals`
The identifier of the service to highlight in the main menu.
See [services.json](src/services.json) for a list of the available service identifiers.
###### Header.skipLinkId
- Type: `String | null`
- Default: `'content-start'`
The identifier of the skip link target.
An empty div with this id will be created at the end of the header, if it doesn't already exist on the page.
###### Header.renderSearchOnly
- Type: `boolean`
- Default: `false`
Optionally render the header with search box only to aid with debugging by reducing noise in the rendered output.
###### Header.onNavigating
- Type: `String | Function`
- Default: `null`
Function parameters:
- `element` (`HTMLAnchorElement`) the HTML anchor element that was clicked to trigger the navigation
- `href` (`String`) the href of the link that was clicked
Currently `onNavigating` _only_ applies to the sub navigation.
Pass `onNavigating` to prevent default of the default navigation behaviour and
provide your own implementation. Pass either a function, or the name of a
function defined on `window`. E.g.:
```js
window.onNavigatingHandler = function (e) {
// Define your implementation here e.g.:
if (e.href === '/#browse') {
// Trigger some custom behaviour
} else window.location.assign(e.href); // Fallback to navigation as normal
};
var global_nav_config = {
header: {
onNavigating: 'onNavigatingHandler',
},
};
```
###### Header.onResize
- Type: `String | Function`
- Default: `null`
Pass an `onResize` function to handle when the header is resized. This includes banners being closed/collapsed:
```js
var global_nav_config = {
header: {
onResize: function () {
// Define your resize implementation here
},
},
};
```
Or the name of a function defined on `window`. E.g.:
```js
window.onResizeHandler = function () {
// Define your resize implementation here
};
var global_nav_config = {
header: {
onResize: 'onResizeHandler',
},
};
```
###### Header.onDropdownOpen
- Type: `String`, `Function`
- Default: `null`
Pass an `onDropdownOpen` property to enable callback when dropdown is open.
Pass either a function, or the name of a function defined on `window`. E.g.:
```js
window.onDropdownOpenHandler = function () {
// Define your implementation here e.g.:
document.querySelector("body").classList.add("global-nav__dropdown--open");
};
var global_nav_config = {
header: {
onDropdownOpen: 'onDropdownOpenHandler',
},
};
```
###### Header.onDropdownClose
- Type: `String`, `Function`
- Default: `null`
Pass an `onDropdownClose` property to enable callback when dropdown is closed.
Pass either a function, or the name of a function defined on `window`. E.g.:
```js
window.onDropdownCloseHandler = function (e) {
// Define your implementation here e.g.:
document.querySelector("body").classList.remove("global-nav__dropdown--open")
};
var global_nav_config = {
header: {
onDropdownClose: 'onDropdownCloseHandler',
},
};
```
###### Header.additionalSubMenuItems
- Type: `null | Array`
- Default: `null`
Pass an `additionalSubMenuItems` array to add extra sub menu items for a given service.
The array should be an array of objects, each containing a `service: string` and another array of `links: Array`.
The links array should contain an array of `text: string` and `url: string`. E.g:
```js
const adminMenus = [{
service: "indev",
links: [{text: "Admin", url: "/admin"}]
},{
service: "publications",
links: [{text: "Admin", url: "/admin"}]
}];
var global_nav_config = {
header: {
additionalSubMenuItems: adminMenus,
},
};
```
###### Header.search
- Type: `Boolean | Object`
- Default: `{}`
Search is enabled by default, pass `false` to disable it e.g. ``.
Or pass a set of key/value pairs to configure search and autocomplete:
###### Header.search.url
- Type: `String`
- Default: `/search`
The url of the search results page that the search form submits a GET request to.
For example submitting a search term _paracetamol_ with a url of _/search_ will go to _/search?q=paracetamol_.
###### Header.search.autocomplete
- Type: `Boolean | String | Array | AutoCompleteOptions`
- Default: `false`
The source for autocomplete (typeahead) suggestions. Set to `false` to disable autocomplete.
Pass an array of objects to use as the source. The objects in the array should have two keys of `Title: string` and `Link: string`, with an optional `TitleHtml: string` and `TypeAheadType: string`. E.g.:
```jsx
const suggestions = [
{ Title: 'Achilles tendinopathy', Link: '/achilles-tendinopathy' },
{ Title: 'Acne vulgaris', Link: '/acne-vulgaris', TitleHtml: 'Acne vulgaris', TypeAheadType: 'keyword' },
];
;
```
Pass a string, not containing a slash, to use a variable with that name on `window` e.g. ``. This is useful for when the suggestions are loaded asynchronously after page load.
Or to make a _remote call_ to a URL on demand, if the source name _does_ contain a slash e.g. ``.
The response is expected to be JSON in the format `Array<{ Title: string, TitleHtml?: string, Link: string }>` e.g.:
```json
[
{
"Title": "Paracetamol",
"Link": "/search?q=Paracetamol"
},
{
"Title": "Paracetamol",
"TitleHtml": "Paracetamol",
"Link": "/search?q=Paracetamol",
"TypeAheadType": "keyword"
}
]
```
Or to customise the template for autocomplete suggestions, pass an object with `suggestions` and `suggestionTemplate`, for example:
```jsx
const autocompleteOptions = {
// Suggestions can be either the name of a variable, a remote url starting with a slash or an array
suggestions: "/a-remote-url",
// Return an HTML string, for example:
suggestionTemplate: (suggestion) => {
if (!suggestion || !suggestion.Link) return "";
return `${
suggestion.TitleHtml || suggestion.Title
}`;
}
};
;
```
If you're using TypeScript, then you can import types e.g.:
```tsx
import { AutoCompleteSuggestions, AutoCompleteOptions } from "@nice-digital/global-nav";
```
###### Header.search.placeholder
- Type: `String`
- Default: `Search NICE…`
Override the placeholder (and label) of the search input box, for example change to _Search BNF…_ for the BNF microsite.
###### Header.search.query
- - Type: `String`
- Default: `""`
The search query term, usually taken from the q value of the querstring.
> If you're using .NET, use [HttpUtility.JavaScriptStringEncode](https://docs.microsoft.com/en-us/dotnet/api/system.web.httputility.javascriptstringencode) to avoid XSS attacks and make sure [Request Validation](https://docs.microsoft.com/en-us/aspnet/whitepapers/request-validation) is enabled.
> Note: old TopHat looked for the q querystring value itself, but with Global Nav it's the responsibility of each application to pass in the search term.
###### Header.search.onSearching
- Type: `String`, `Function`
- Default: `null`
Function parameters:
- `query` (`String`) the query term used in the search
The search form by default submits a GET request to `/search?q=XYZ`.
Disable this and provide your own implementation by passing an `onSearching` property.
Pass either a function, or the name of a function defined on `window`. E.g.:
```js
window.onSearchingHandler = function (e) {
// Define your implementation here e.g.:
window.location.assign('/search?q=' + encodeURIComponent(e.query));
};
var global_nav_config = {
header: {
search: {
onSearching: 'onSearchingHandler',
},
},
};
```
###### Header.auth
- Type: `Boolean | Object`
- Default: `{}`
Authentication is enabled by default. Disable authentication by passing `false`:
```js
// React:
// Or config:
var global_nav_config = {
header: {
auth: false,
},
};
```
Pass a set of key/value pairs to configure authentication, for example:
```js
// React
// Or config:
var global_nav_config = {
header: {
auth: { environment: 'live', provider: 'niceAccounts' },
},
};
```
See the `header.auth` properties below for how to configure authentication providers.
###### Header.auth.environment
- Type: `String`
- Default: `live`
- Values: `live`, `test`, `beta`, `local`
This value is the authentication environment eg `beta` would be _beta-accounts.nice.org.uk_.
###### Header.auth.provider
- Type: `String`
- Default: `niceAccounts`
- Values: `niceAccounts`, `idam`
The authentication provider allows the provider to be changed. If the provider is set to niceAccounts then an environment be defined. If the provider is set to idam the links and displayName must be defined.
###### Header.auth.links
- Type: `Array | null`
- Default: `null`
- Values: `[{ key: "Sign in", value: "/Account/Login" }]`, `[{ key: "My profile", value: "/Account/profile" },{ key: "Sign out", value: "/Account/Logout" }]`
If the authentication provider has been set to "idam", then an array of links must be provided. If the user is logged out then a "Sign in" link should be provided with an appropriate url supplied - this should be the first in the list. If the user is logged in, then a number of links are supported, with a "Sign out" link normally last in the list, also a displayName must be supplied.
###### Header.auth.displayName
- Type: `String | null`
- Default: `null`
The displayName is the user's name and must be provided if the "idam" provider is used and the user is logged in.
##### Footer props
###### Footer.service
- Type: `String | null`
- Default: `''`
- Values: `pathways`, `guidance`, `standards`, `evidence`, `bnf`, `bnfc`, `cks`, `journals`
The identifier of the currently active service.
See [services.json](src/services.json) for a list of the available service identifiers.
### CDN
Reference the Global Nav bundle directly from the NICE CDN to render the Global Nav. We recommend including this before the closing `