{"id":50467972,"url":"https://github.com/nice-digital/global-nav-par","last_synced_at":"2026-06-01T08:32:43.055Z","repository":{"id":360415051,"uuid":"1230941646","full_name":"nice-digital/global-nav-par","owner":"nice-digital","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-26T09:59:41.000Z","size":351,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T11:04:07.834Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nice-digital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T13:22:21.000Z","updated_at":"2026-05-26T09:59:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nice-digital/global-nav-par","commit_stats":null,"previous_names":["nice-digital/global-nav-par"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nice-digital/global-nav-par","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fglobal-nav-par","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fglobal-nav-par/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fglobal-nav-par/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fglobal-nav-par/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nice-digital","download_url":"https://codeload.github.com/nice-digital/global-nav-par/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fglobal-nav-par/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T08:32:42.239Z","updated_at":"2026-06-01T08:32:43.042Z","avatar_url":"https://github.com/nice-digital.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Global navigation\n\n\u003e Global header and footer used across all NICE digital services\n\n[**:rocket: Jump straight to getting started**](#rocket-set-up)\n\n[![GitHub release](https://img.shields.io/github/release/nice-digital/global-nav/all.svg)](https://github.com/nice-digital/global-nav)\n[![GitHub license](https://img.shields.io/github/license/nice-digital/global-nav.svg)](https://github.com/nice-digital/global-nav/blob/master/LICENSE)\n[![NICE Design System](https://img.shields.io/static/v1.svg?logoWidth=40\u0026label=\u0026message=DESIGN%20SYSTEM\u0026color=004650\u0026labelColor=393939\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNDEwIiBoZWlnaHQ9IjUxMiIgZmlsbD0ibm9uZSI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTQxMi4wOTYgNDU0LjA3YzAgMTYuMTQ2LTYuNzkgMTkuMjQtMTcuOTQgMTkuMjRoLTUyLjYyNGMtMTEuMTQ5IDAtMjAuNDA5LTQuMzUxLTI3LjI1Ny0xMy42NTJMMTI5LjgyMSAyMTMuMzE1aC0xLjI1NHYyNDEuMzc0YzAgMTMuNjUxLTYuMTkyIDE4LjYwMS0xOC41NTcgMTguNjAxSDUyLjQyODRDMzguMTkyMiA0NzMuMjkgMzIgNDcwLjE5NyAzMiA0NTUuMjg4VjYxLjkxMzFjMC0xNi4xMjY0IDcuNDI2OC0xOS4yMzk1IDIwLjQyODQtMTkuMjM5NWg1MS45ODc2YzEyLjM2NSAwIDE4LjU1NyAzLjczMTkgMjUuMzY3IDEzLjAzMjZMMzE0LjIzNyAzMDMuOTA1aDEuMjM0VjYwLjY1NjJjMC0xMy42MzIgNi44MS0xNy45ODI2IDE5LjE5NC0xNy45ODI2aDYwLjA1MWMxNi4wODggMCAxNy4zMjMgOC42ODE5IDE3LjMyMyAxOS4yMzk1VjQ1NC4wNTFoLjAzOGwuMDE5LjAxOXptMTk3LjMwMiAzLjU3N2MwIDcuNDQ1LTQuOTM5IDE0LjI5LTEzLjYgMTQuMjloLTcxLjIwMWMtOS4yNTkgMC0xMy41OTktNi44NDUtMTMuNTk5LTEzLjY1MVY1NS41NTE1YzAtNy40NDQ1IDQuOTU3LTE0LjI1MDggMTMuNTk5LTE0LjI1MDhoNzEuMjAxYzkuMjc5IDAgMTMuNiA2LjgwNjMgMTMuNiAxMy42NTE0VjQ1Ny42NDd6TTEwMjUuNDEgNzcuOTA0MWwtMTcuOTYgNTIuMTI5OWMtMi40NSA2LjIwNy00LjkzIDkuMzAxLTkuMjU2IDkuMzAxLTIuNDY5IDAtNC45MzgtMS4yMzctOC4wNDQtMi40OTQtMzIuODEzLTE1LjQ4OC01OC4xOTktMjEuMDk2LTg3LjI2OS0yMS4wOTYtNjQuMzkxIDAtMTA1Ljg0NiA0OS42MzYtMTA1Ljg0NiAxNDAuMjI2IDAgOTguMDU0IDQ3LjAxIDE0MC4yMDcgMTA3LjcxNyAxNDAuMjA3IDI5LjA5IDAgNTQuNDc2LTUuNTMgODMuNTQ2LTE3LjMyNiAzLjcwNC0xLjI3NiA2LjgyOS0yLjQ5NCA5LjI3OS0yLjQ5NCA1LjU3MyAwIDguNjYzIDIuNDk0IDExLjEzMyA5LjkybDE1LjQ5IDQ1Ljk0MmMxLjIzIDMuNzEzIDEuODUgNi44MDcgMS44NSA5LjkyIDAgNi4yMDctMi40NyAxMC41NTctMTEuMTUgMTMuNjUxQzk3Mi4xOTEgNDcxLjkzNyA5MzYuODg5IDQ4MCA4ODkuMjQyIDQ4MGMtMTMxLjIzMiAwLTE5Ny40NTUtODcuNDk2LTE5Ny40NTUtMjIwLjg5N0M2OTEuNzg3IDEyNS4wNjUgNzcyLjg2NCAzMiA4OTcuMjg2IDMyYzQ0LjU4IDAgODIuMzUxIDguNzAxMyAxMTguMjM0IDI0LjgyNzcgOC42OCAzLjcxMjUgMTEuNzggOC4wNjMyIDExLjc4IDEyLjM5NDUuMDIgMi40OTQzLS42MSA1LjU4ODEtMS44NyA4LjcwMTJsLS4wMi0uMDE5M3ptMzM3LjA2LTM2LjYyMjdjMTIuMzkgMCAxNi4wNyA2LjIwNjkgMTUuNDcgMTQuMjUwN2wtNS41NyA1MC4yNzM5Yy0xLjI0IDEzLjAzMy05LjI4IDE1LjUyNy0yNC4xMyAxNS41MjdoLTE0OS44M3Y5Mi40MjdoMTQwLjUzYzEzLjY0IDAgMTguNTcgNi44MjYgMTguNTcgMTYuNzQ1djQ1LjI4NmMwIDEyLjQzMy02LjE5IDE4LjAwMi0xNy45NCAxOC4wMDJoLTE0MS4xNHY5OC4wNzNIMTM2MGMxMS4xMyAwIDE3Ljk2IDQuOTMgMTcuOTYgMTYuNzI2djQ1Ljk0MmMwIDExLjc3Ni01LjU3IDE3LjM2NC0xNy4zMiAxNy4zNjRoLTI0MC4yMmMtMTQuMjQgMC0yMC40MS0zLjczMi0yMC40MS0xOS4yMzlWNTguNjQ1M2MwLTEwLjU1NzYgNS41Ny0xNy4zNjM5IDE2LjA5LTE3LjM2MzlsMjQ2LjM3LS4wMTk0di4wMTk0eiIvPjwvc3ZnPg==)](https://github.com/nice-digital/nice-design-system)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e:bookmark_tabs: Table of contents (click to expand)\u003c/strong\u003e\u003c/summary\u003e\n\n\u003c!-- START doctoc --\u003e\n\n- [Global navigation](#global-navigation)\n  - [What is it?](#what-is-it)\n    - [Functionality](#functionality)\n    - [Non-functional](#non-functional)\n  - [Stack](#stack)\n    - [Principles](#principles)\n    - [CSS Modules](#css-modules)\n  - [:rocket: Set up](#rocket-set-up)\n    - [Other commands](#other-commands)\n      - [Tests](#tests)\n        - [Run individual files](#run-individual-files)\n        - [Run individual tests](#run-individual-tests)\n      - [Linting](#linting)\n      - [Production build](#production-build)\n    - [IDE](#ide)\n      - [Extensions](#extensions)\n    - [Gotchas](#gotchas)\n  - [How to use](#how-to-use)\n    - [React](#react)\n      - [Installation](#installation)\n      - [Usage](#usage)\n      - [Props](#props)\n        - [Main props](#main-props)\n          - [Main.withPadding](#mainwithpadding)\n        - [Header props](#header-props)\n          - [Header.service](#headerservice)\n          - [Header.skipLinkId](#headerskiplinkid)\n          - [Header.renderSearchOnly](#headerrendersearchonly)\n          - [Header.onNavigating](#headeronnavigating)\n          - [Header.onResize](#headeronresize)\n          - [Header.onDropdownOpen](#headerondropdownopen)\n          - [Header.onDropdownClose](#headerondropdownclose)\n          - [Header.additionalSubMenuItems](#headeradditionalsubmenuitems)\n          - [Header.search](#headersearch)\n          - [Header.search.url](#headersearchurl)\n          - [Header.search.autocomplete](#headersearchautocomplete)\n          - [Header.search.placeholder](#headersearchplaceholder)\n          - [Header.search.query](#headersearchquery)\n          - [Header.search.onSearching](#headersearchonsearching)\n          - [Header.auth](#headerauth)\n          - [Header.auth.environment](#headerauthenvironment)\n          - [Header.auth.provider](#headerauthprovider)\n          - [Header.auth.links](#headerauthlinks)\n          - [Header.auth.displayName](#headerauthdisplayname)\n        - [Footer props](#footer-props)\n          - [Footer.service](#footerservice)\n    - [CDN](#cdn)\n      - [Container IDs](#container-ids)\n      - [Overrides](#overrides)\n      - [Configuration](#configuration)\n        - [service](#service)\n        - [header](#header)\n          - [header.onRendering](#headeronrendering)\n          - [header.onRendered](#headeronrendered)\n        - [footer](#footer)\n  - [Deployments](#deployments)\n  - [Upgrading to v2](#upgrading-to-v2)\n  - [Upgrading to v3](#upgrading-to-v3)\n  - [Upgrading to v4](#upgrading-to-v4)\n  - [Upgrading to v5](#upgrading-to-v5)\n  - [Upgrading to v6](#upgrading-to-v6)\n\n\u003c!-- END doctoc --\u003e\n\u003c/details\u003e\n  \n## What is it?\n\nGlobal 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).\n\n### Functionality\n\nThe header covers the following high-level functionality:\n\n- main navigation\n- skip links\n- search and autocomplete\n- COVID-19 message\n- TLS warning message for old IE\n- sign in and account management via NICE Accounts\n  - In the future will support Auth0\n\n### Non-functional\n\nThe following non-functional requirements apply:\n\n- _accessible_: to WCAG 2.0 AA\n- _touch_: optimized for touch with sufficient touch targets\n- _print_: print styles\n- _security_: tested against OWASP top 10 and pen tested\n- _progressive enhancement_:\n  - mobile first\n  - non-JS fallback for SSR React apps\n- _browser support_: IE11+\n\n## Stack\n\n- [React](https://reactjs.org/)\n- [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html) for styles\n- [CSS Modules](https://github.com/css-modules/css-modules) for generated class names\n- [PostCSS](https://postcss.org/) for transforming CSS with plugins:\n  - [autoprefixer](https://autoprefixer.github.io/) for automatically adding vendor prefixes in CSS\n  - and [NICE Digital shared browserslist config](https://github.com/nice-digital/browserslist-config#readme)\n- [Vite](https://vitejs.dev/) for module bundling\n- [Babel 7](https://babeljs.io/) for ES6/JSX → ES5 transpilation\n- [accessible-autocomplete](https://github.com/alphagov/accessible-autocomplete)\n- [ESLint](https://eslint.org/) for linting our JavaScript\n  - with [NICE Digital shared eslint config](https://www.npmjs.com/package/@nice-digital/eslint-config)\n- [Stylelint](https://stylelint.io/) for linting our SCSS\n- [Prettier](https://prettier.io/) for code formatting\n- [Jest](https://jestjs.io/) for JS unit tests and snapshot tests\n- [NICE Design System](https://nice-digital.github.io/nice-design-system/) core for SASS mixins, functions and colour/spacing variables\n  - [NICE Icons](https://github.com/nice-digital/nice-icons)\n\n### Principles\n\nConsider the following development principles:\n\n- One single header and footer component (and optional main wrapper component with back to top link) across _all_ NICE services\n- Progressively enhanced to support maximum number of devices and browsers\n- Fast performance\n  - single HTTP request for CDN minified bundle\n  - as small as possible bundle size\n- High unit test coverage\n- 'Standard' React wherever possible\n  - easy for any React developer to pickup\n- Consistent code style and formatting\n  - as if a single developer worked across the codebase\n- Clear extension points and hooks for integrating into applications\n  - To avoid some of the issues from TopHat where there was no consistency\n\n### CSS Modules\n\nWe use SCSS modules for a few reasons:\n\n- local scoping of SCSS avoids accidental cascades:\n  - within global nav\n  - polluting out of global nav into the global scope\n- obfuscated class names discourages overriding CSS styles in your app. This is by design to keep the header consistent across all services.\n\nUsing SCSS allows us to use mixins, functions and variables from the NICE Design System.\n\n\u003e If you _really_ need to override styles, see the [overrides documentation](#overrides).\n\n## :rocket: Set up\n\n**TL;DR;** to run the project locally, do the following:\n\n- 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.\n- run `npm ci` on the command line to install dependencies\n- run `npm run dev` on the command line\n- navigate to \u003chttp://localhost:3000/\u003e in a browser.\n\nThis compiles the application and spins up a development server. It then watches for changes to files and:\n\n- lints changed files\n- automatically rebuilds the app.\n\nIt 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/).\n\n### Other commands\n\nThere are various other commands you can run for further things like tests and linting:\n\n#### Tests\n\n- `npm test` Lints code and runs tests\n- `npm test:unit` Runs Jest unit tests\n- `npm test:unit:watch` Runs Jest unit tests and watches for changes. Run this in development.\n- `npm test:unit:coverage` Runs Jest unit tests and reports coverage\n\nIf you've installed the [VSCode npm extension](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) then you can easily run scripts by:\n\n- right-clicking the script name in _package.json_\n- or _Ctrl+Shift+P_ -\u003e _npm run script_ -\u003e _test:unit:watch_.\n\n##### Run individual files\n\nTo 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_:\n\n```sh\nnpm run-script test:unit -- nav\n```\n\n##### Run individual tests\n\nTo 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:\n\n```sh\nnpm run-script test:unit -- -t aria\n```\n\n#### Linting\n\n- `npm run lint` Lints both JavaScript and SCSS\n- `npm run prettier` Checks files for Prettier code style\n- `npm run prettier:fix` Fixes Prettier code style issues\n- `npm run lint:js` Lints just JavaScript files\n- `npm run lint:js:fix` Fixes linting issues automatically in JavaScript files\n- `npm run lint:scss` Lints just SCSS files\n- `npm run lint:scss:fix` Fixes linting issues automatically in SCSS files\n\n#### Production build\n\nTo 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:\n\n```bash\nrun build:teamcity vite build\n```\n\n### IDE\n\nWe 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:\n\n#### Extensions\n\nThe following VS Code extensions are **strongly** recommended, but not required:\n\n- [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\n- [stylelint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint) - this will highlight SCSS linting errors directly in the IDE\n- [eslint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint) - automatically lints your JavaScript as you type and highlights any errors\n- [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\n- [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\n- [Jest](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest) for automatically running tests and highlighting errors in the IDE\n\n### Gotchas\n\n- Check you have the right version of Node installed\n- Make sure have LF line endings as this is a cross-platform project. This _should_ happen automatically because of settings in _.gitattributes_ and _.editorconfig_.\n- Watch out for features of React that Nerv doesn't support, for example refs.\n\n## How to use\n\nWe support 2 main methods for using the Global Nav in your projects:\n\n- as a [React component](#react) installed directly into your app\n- or externally to your app, loaded via the [CDN](#cdn).\n\n### React\n\nInstall and use Global Nav as a dependency in a React application to include it as part of your application bundle.\n\nThis 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/).\n\n\u003e Note if you're using Create React App you'll need to use v2+ because we use CSS modules\n\nInstall the package and require the `Header`, `Footer` and `Main` React components into your application, just as you would for any other 3rd party component:\n\n#### Installation for new projects\n\nFirst, install the _@nice-digital/global-nav_ package [from npm](https://www.npmjs.com/package/@nice-digital/global-nav) into your project:\n\n```sh\nnpm i @nice-digital/global-nav --save\n```\n\n\u003e 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.\n\nThen, require the header and/or footer and/or main into your application:\n\n#### Usage\n\nImport the header, footer and main component like this:\n\n```js\nimport { Header, Footer, Main } from '@nice-digital/global-nav';\n```\n\n\u003e Note: we've used ES6 module imports for this examples as we've assumed all React apps will be using ES6.\n\nThese header, footer and main components that can be be used like any other React component and configured via [props](#props), for example:\n\n```jsx\nconst search = {\n  autocomplete: '/autocomplete',\n};\n\nconst page = () =\u003e (\n  \u003cdiv\u003e\n    \u003cHeader service=\"guidance\" search={search} /\u003e\n  \u003cMain withPadding={true} myOptionalProp={myOptionalProp} className=\"my-optional-class\" \u003e{/* Your page content here */} \u003c/Main\u003e\n    \u003cFooter /\u003e\n  \u003c/div\u003e\n);\n```\n\nWrapping your template with the main component will render a main tag in the html with a back to top link.\n\nFor a full list of all the available props, see the [props section](#props) below:\n\n#### Props\n\n##### Main props\n\n###### Main.withPadding\n\n- Type: `Boolean`\n- Default: true\n  \nOptional spacing between page content and footer back-to-top link.\n\n##### Header props\n\n###### Header.service\n\n- Type: `String | null`\n- Default: `''`\n- Values: `guidance`, `standards`, `evidence`, `bnf`, `bnfc`, `cks`, `journals`\n\nThe identifier of the service to highlight in the main menu.\nSee [services.json](src/services.json) for a list of the available service identifiers.\n\n###### Header.skipLinkId\n\n- Type: `String | null`\n- Default: `'content-start'`\n\nThe identifier of the skip link target.\nAn empty div with this id will be created at the end of the header, if it doesn't already exist on the page.\n\n###### Header.renderSearchOnly\n\n- Type: `boolean`\n- Default: `false`\n\nOptionally render the header with search box only to aid with debugging by reducing noise in the rendered output.\n\n###### Header.onNavigating\n\n- Type: `String | Function`\n- Default: `null`\n\nFunction parameters:\n\n- `element` (`HTMLAnchorElement`) the HTML anchor element that was clicked to trigger the navigation\n- `href` (`String`) the href of the link that was clicked\n\nCurrently `onNavigating` _only_ applies to the sub navigation.\n\nPass `onNavigating` to prevent default of the default navigation behaviour and\nprovide your own implementation. Pass either a function, or the name of a\nfunction defined on `window`. E.g.:\n\n```js\nwindow.onNavigatingHandler = function (e) {\n  // Define your implementation here e.g.:\n\n  if (e.href === '/#browse') {\n    // Trigger some custom behaviour\n  } else window.location.assign(e.href); // Fallback to navigation as normal\n};\n\nvar global_nav_config = {\n  header: {\n    onNavigating: 'onNavigatingHandler',\n  },\n};\n```\n\n###### Header.onResize\n\n- Type: `String | Function`\n- Default: `null`\n\nPass an `onResize` function to handle when the header is resized. This includes banners being closed/collapsed:\n\n```js\nvar global_nav_config = {\n  header: {\n    onResize: function () {\n      // Define your resize implementation here\n    },\n  },\n};\n```\n\nOr the name of a function defined on `window`. E.g.:\n\n```js\nwindow.onResizeHandler = function () {\n  // Define your resize implementation here\n};\n\nvar global_nav_config = {\n  header: {\n    onResize: 'onResizeHandler',\n  },\n};\n```\n\n###### Header.onDropdownOpen\n\n- Type: `String`, `Function`\n- Default: `null`\n\nPass an `onDropdownOpen` property to enable callback when dropdown is open.\nPass either a function, or the name of a function defined on `window`. E.g.:\n\n```js\nwindow.onDropdownOpenHandler = function () {\n  // Define your implementation here e.g.:\n  document.querySelector(\"body\").classList.add(\"global-nav__dropdown--open\");\n};\n\nvar global_nav_config = {\n  header: {\n      onDropdownOpen: 'onDropdownOpenHandler',\n  },\n};\n```\n\n###### Header.onDropdownClose\n\n- Type: `String`, `Function`\n- Default: `null`\n\nPass an `onDropdownClose` property to enable callback when dropdown is closed.\nPass either a function, or the name of a function defined on `window`. E.g.:\n\n```js\nwindow.onDropdownCloseHandler = function (e) {\n  // Define your implementation here e.g.:\n document.querySelector(\"body\").classList.remove(\"global-nav__dropdown--open\")\n\n};\n\nvar global_nav_config = {\n  header: {\n      onDropdownClose: 'onDropdownCloseHandler',\n  },\n};\n```\n\n###### Header.additionalSubMenuItems\n\n- Type: `null | Array`\n- Default: `null`\n\nPass an `additionalSubMenuItems` array to add extra sub menu items for a given service.\n\nThe array should be an array of objects, each containing a `service: string` and another array of `links: Array`.\nThe links array should contain an array of `text: string` and `url: string`. E.g:\n\n```js\nconst adminMenus = [{\n    service: \"indev\",\n    links: [{text: \"Admin\", url: \"/admin\"}]\n  },{\n    service: \"publications\",\n    links: [{text: \"Admin\", url: \"/admin\"}]\n  }];\n\nvar global_nav_config = {\n  header: {\n    additionalSubMenuItems: adminMenus,\n  },\n};\n```\n\n###### Header.search\n\n- Type: `Boolean | Object`\n- Default: `{}`\n\nSearch is enabled by default, pass `false` to disable it e.g. `\u003cHeader search={false} /\u003e`.\nOr pass a set of key/value pairs to configure search and autocomplete:\n\n###### Header.search.url\n\n- Type: `String`\n- Default: `/search`\n\nThe url of the search results page that the search form submits a GET request to.\nFor example submitting a search term _paracetamol_ with a url of _/search_ will go to _/search?q=paracetamol_.\n\n###### Header.search.autocomplete\n\n- Type: `Boolean | String | Array\u003cAutoCompleteSuggestion\u003e | AutoCompleteOptions`\n- Default: `false`\n\nThe source for autocomplete (typeahead) suggestions. Set to `false` to disable autocomplete.\n\nPass 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.:\n\n```jsx\nconst suggestions = [\n  { Title: 'Achilles tendinopathy', Link: '/achilles-tendinopathy' },\n  { Title: 'Acne vulgaris', Link: '/acne-vulgaris', TitleHtml: '\u003cmark\u003eAcne\u003c/mark\u003e vulgaris', TypeAheadType: 'keyword' },\n];\n\u003cHeader search={{ autocomplete: suggestions }} /\u003e;\n```\n\nPass a string, not containing a slash, to use a variable with that name on `window` e.g. `\u003cHeader search={{ autocomplete: \"topics\" }} /\u003e`. This is useful for when the suggestions are loaded asynchronously after page load.\n\nOr to make a _remote call_ to a URL on demand, if the source name _does_ contain a slash e.g. `\u003cHeader search={{ autocomplete: \"/autocomplete?ajax=ajax\" }} /\u003e`.\n\nThe response is expected to be JSON in the format `Array\u003c{ Title: string, TitleHtml?: string, Link: string }\u003e` e.g.:\n\n```json\n[\n  {\n    \"Title\": \"Paracetamol\",\n    \"Link\": \"/search?q=Paracetamol\"\n  },\n  {\n    \"Title\": \"Paracetamol\",\n    \"TitleHtml\": \"\u003cmark\u003ePara\u003c/mark\u003ecetamol\",\n    \"Link\": \"/search?q=Paracetamol\",\n  \"TypeAheadType\": \"keyword\"\n  }\n]\n```\n\nOr to customise the template for autocomplete suggestions, pass an object with `suggestions` and `suggestionTemplate`, for example:\n\n```jsx\nconst autocompleteOptions = {\n  // Suggestions can be either the name of a variable, a remote url starting with a slash or an array\n  suggestions: \"/a-remote-url\",\n  // Return an HTML string, for example:\n  suggestionTemplate: (suggestion) =\u003e {\n   if (!suggestion || !suggestion.Link) return \"\";\n   return `\u003ca href=\"${suggestion.Link}\"\u003e${\n    suggestion.TitleHtml || suggestion.Title\n   }\u003c/a\u003e`;\n  }\n };\n\n\u003cHeader search={{\n  autocomplete: autocompleteOptions\n }} /\u003e;\n```\n\nIf you're using TypeScript, then you can import types e.g.:\n\n```tsx\nimport { AutoCompleteSuggestions, AutoCompleteOptions } from \"@nice-digital/global-nav\";\n```\n\n###### Header.search.placeholder\n\n- Type: `String`\n- Default: `Search NICE…`\n\nOverride the placeholder (and label) of the search input box, for example change to _Search BNF…_ for the BNF microsite.\n\n###### Header.search.query\n\n- - Type: `String`\n- Default: `\"\"`\n\nThe search query term, usually taken from the q value of the querstring.\n\n\u003e 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.\n\n\u003e 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.\n\n###### Header.search.onSearching\n\n- Type: `String`, `Function`\n- Default: `null`\n\nFunction parameters:\n\n- `query` (`String`) the query term used in the search\n\nThe search form by default submits a GET request to `/search?q=XYZ`.\nDisable this and provide your own implementation by passing an `onSearching` property.\nPass either a function, or the name of a function defined on `window`. E.g.:\n\n```js\nwindow.onSearchingHandler = function (e) {\n  // Define your implementation here e.g.:\n  window.location.assign('/search?q=' + encodeURIComponent(e.query));\n};\n\nvar global_nav_config = {\n  header: {\n    search: {\n      onSearching: 'onSearchingHandler',\n    },\n  },\n};\n```\n\n###### Header.auth\n\n- Type: `Boolean | Object`\n- Default: `{}`\n\nAuthentication is enabled by default. Disable authentication by passing `false`:\n\n```js\n// React:\n\u003cHeader auth={false} /\u003e\n\n// Or config:\nvar global_nav_config = {\n  header: {\n    auth: false,\n  },\n};\n```\n\nPass a set of key/value pairs to configure authentication, for example:\n\n```js\n// React\n\u003cHeader auth={{ environment: 'live', provider: 'niceAccounts' }} /\u003e\n\n// Or config:\nvar global_nav_config = {\n  header: {\n    auth: { environment: 'live', provider: 'niceAccounts' },\n  },\n};\n```\n\nSee the `header.auth` properties below for how to configure authentication providers.\n\n###### Header.auth.environment\n\n- Type: `String`\n- Default: `live`\n- Values: `live`, `test`, `beta`, `local`\n\nThis value is the authentication environment eg `beta` would be _beta-accounts.nice.org.uk_.\n\n###### Header.auth.provider\n\n- Type: `String`\n- Default: `niceAccounts`\n- Values: `niceAccounts`, `idam`\n\nThe 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.\n\n###### Header.auth.links\n\n- Type: `Array | null`\n- Default: `null`\n- Values: `[{ key: \"Sign in\", value: \"/Account/Login\" }]`, `[{ key: \"My profile\", value: \"/Account/profile\" },{ key: \"Sign out\", value: \"/Account/Logout\" }]`\n\nIf 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.\n\n###### Header.auth.displayName\n\n- Type: `String | null`\n- Default: `null`\n\nThe displayName is the user's name and must be provided if the \"idam\" provider is used and the user is logged in.\n\n##### Footer props\n\n###### Footer.service\n\n- Type: `String | null`\n- Default: `''`\n- Values: `pathways`, `guidance`, `standards`, `evidence`, `bnf`, `bnfc`, `cks`, `journals`\n\nThe identifier of the currently active service.\nSee [services.json](src/services.json) for a list of the available service identifiers.\n\n### CDN\n\nReference the Global Nav bundle directly from the NICE CDN to render the Global Nav. We recommend including this before the closing `\u003c/body\u003e` tag but before your application's scripts:\n\n```html\n\u003cscript src=\"//cdn.nice.org.uk/global-nav/global-nav.min.js\"\u003e\u003c/script\u003e\n```\n\nThis renders with the default configuration. See [the configuration section below](#configuration) for how to pass options into the Global Nav.\n\n\u003e Note: you can reference the non-minified version by removing _.min_ from the filename.\n\nReference a specific version of the global nav by including the build number as a sub folder. This is useful for testing, in case of a breaking change, or in case of needing to roll back for a hotfix, for example:\n\n```html\n\u003cscript src=\"//alpha-cdn.nice.org.uk/global-nav/4.1.806-GN-180-FixInDev/global-nav.min.js\"\u003e\u003c/script\u003e\nor\n\u003cscript src=\"//cdn.nice.org.uk/global-nav/4.1.805%2Br6D13311/global-nav.min.js\"\u003e\u003c/script\u003e\n```\n\nNote the production build needs the `+` character in the build metadata encoding as `%2B` to avoid browsers interpreting it as a space in the URL.\n\n#### Container IDs\n\nThe CDN version of Global Nav creates its own containers for the header and footer if they don't already exist on the page. These containers use the ids:\n\n- `global-nav-header` for the header\n- `global-nav-footer` for the footer.\n\nInclude empty elements with these ids on the page and Global Nav will render into these instead of creating its own:\n\n```html\n\u003cbody\u003e\n  \u003cdiv id=\"global-nav-header\"\u003e\u003c/div\u003e\n  \u003cmain\u003e\n    \u003c!-- Your page content here --\u003e\n  \u003c/main\u003e\n  \u003cdiv id=\"global-nav-footer\"\u003e\u003c/div\u003e\n  \u003cscript src=\"//cdn.nice.org.uk/global-nav/global-nav.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Overrides\n\nWhere possible, we recommend using the [provided configuration hooks](#configuration) like [`onSearching`](#headersearchonsearching), [`onNavigating`](#headeronnavigating), [`onRendering`](#headeronrendering), [`onRendered`](#headeronrendered) etc for hooking into or overriding default Global Nav behaviours, rather than using unsupported CSS selectors.\n\nUse the `global-nav-header` and `global-nav-footer` ids to target the Global Nav for more bespoke behaviours - these are the only officially supported selector hooks.\n\n\u003e Please don't rely on inner implementations for hooks or overrides.\n\nFor example, if you're targeting the search form via jQuery, use the robust `$(\"#global-nav-header form[role='search']\")` selector rather than `$(\"#global-nav-search-form\")` as this is an inner implementation and might change.\n\nTry not to override Global Nav styles in your app: the Global Nav exists to give consistency across NICE digital services. If you _really_ have to, then same rules as apply as above. For example in CSS:\n\n```css\n#global-nav-header {\n  position: relative;\n}\n```\n\n#### Configuration\n\nGlobal Nav configuration is loaded from a global JavaScript variable on the window object called `global_nav_config`. Include this variable before the [cdn script include](#cdn). Here's a fulle example of all the available config options:\n\n```js\nvar global_nav_config = {\n  service: 'guidance',\n  header: {\n    skipLinkId: 'content-start',\n    cookie: true,\n    onNavigating: function (e) {\n      // Use e.href\n    },\n    auth: {\n      environment: 'beta',\n      provider: 'niceAccounts',\n    },\n    search: {\n      autocomplete: '/autocomplete?ajax=ajax',\n      url: '/search',\n      placeholder: 'Search NICE…',\n      query: '\"diabetes in pregnancy\"',\n      onSearching: function (e) {\n        // Use e.query\n      },\n    },\n  },\n  footer: false,\n};\n```\n\nThe following config options apply:\n\n##### service\n\n- Type: `String`\n- Default: `null`\n\nThe key of the service to highlight on the navigation elements. See [_src/Header/Nav/links.json_](src/Header/Nav/links.json) for the available options.\n\n##### header\n\n- Type: `Boolean | Object`\n- Default: `null`\n\nThe header renders by default, set `header` to `false` to stop it from rendering e.g. `global_nav_config = { header: false }`.\nOr, pass an object of key/value pairs of settings specific to the header.\nSee the [header props](#header-props) section for available options.\n\nIn addition to the options from the React props, there are also the following callbacks available when rendering using the CDN embed:\n\n###### header.onRendering\n\n- Type: `Function | String` signature: `function(element)`\n- Default: `null`\n\nFunction parameters:\n\n- `element` (`HTMLElement`) the HTML element the header will be rendered in to\n\nA callback function, called just before the header is rendered. If it is a string, then a function with that name will be looked for on `window`.\n\n###### header.onRendered\n\n- Type: `Function | String` signature: `function(element)`\n- Default: `null`\n\nFunction parameters:\n\n- `element` (`HTMLElement`) the HTML the header was rendered in to\n\nA callback function, called just after the header has been rendered. If it is a string, then a function with that name will be looked for on `window`.\n\n##### footer\n\n- Type: `Boolean | Object`\n- Default: `null`\n\nThe footer renders by default, set `footer` to `false` to stop it from rendering e.g. `global_nav_config = { footer: false }`.\nOr, pass an object of key/value pairs of settings specific to the footer.\nSee the [footer props](#footer-props) section for available options.\n\n## Deployments\n\nWe create 2 deployment artifacts: one for deploying to the CDN and one test site for previewing the header and footer.\n\nTo test what the deployment packages looks like locally, run the following command:\n\n```sh\ndotnet pack NICE.GlobalNav.CDN.csproj -o publish /p:Version=1.2.3-r1a2b3c\n# OR dotnet pack NICE.GlobalNav.Preview.csproj -o publish /p:Version=1.2.3-r1a2b3c\n```\n\nWhere the version number can be any valid [SemVer build number](https://octopus.com/blog/semver2) compatible with Octopus Deploy. Note: this version number will be the build number when TeamCity creates this build artifact.\n\n\u003e Note: you'll need the DotNet Core SDK installed. We don't use NuGet.exe to build so we can run on both Windows and Linux\n\n## Upgrading to v2\n\nVersion 2 is a breaking change, because we removed the cookie banner and associated `cookie` option.\n\nIf you were already using `cookie: false` in the header config, then the upgrade is easy - the `cookie: false` will no longer do anything so can safely be removed.\n\nIf you were using `cookie: true` (or not setting the `cookie` option and leaving the default value of `true`) then you will need to include the [cookie banner](https://github.com/nice-digital/cookie-banner#usage) separately from Global Nav.\n\n## Upgrading to v3\n\nVersion 3 removes react hot loader, replacing it with fast refresh. Although this is mostly internal implmenentation, _react-hot-loader_ was a production dependency, and the `Header` and `Footer` components were both exported wrapped in `hot`. So this _could_ affect services using Global Nav as an npm dependency (installed from GitHub).\n\n## Upgrading to v4\n\nV4 involved updating a lot of dependencies. Mostly this was internal implementation details. However, the one external facing change was the build command changing from `npm run build -- --env.version=1.2.3` to `npm run build -- --env version=1.2.3`. Notice the space instead of the dot. This is a result of the `--env` parameter in webpack 4.\n\n## Upgrading to v5\n\nVersion 5 includes updates for the summer 2022 brand refresh. It's mostly an internal refactor of typography and colour updates and shouldn't include any breaking API changes.\n\n## Upgrading to v6\n\nVersion 6 is mostly updates of dependencies, the biggest of which was React Testing Library (from Enzyme). It also includes support for React 18 and Design System v5.\n\n## Upgrading to v7\n\nUpdated autocomplete component.\n\n## Upgrading to v7.1\n\nIn Version 7.1, significant changes to improve the development and build processes of the project have been introduced:\n\n### Migrating to Vite\n\nMigration from Webpack to Vite, a faster build tool. Vite provides improved performance and a better development experience with features like Fast Refresh, which replaces React Hot Loader. Terser minification options enable further optimisation of the bundle size, resulting in approximately 10% reduction in bundle size during the build process.\n\n### Easier transition to TypeScript\n\nWith the migration to Vite, transitioning to TypeScript in the future will be more straightforward. Vite's TypeScript support will make the process smoother when the time comes for the project to adopt TypeScript.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnice-digital%2Fglobal-nav-par","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnice-digital%2Fglobal-nav-par","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnice-digital%2Fglobal-nav-par/lists"}