import { OntarioHeader } from '@ongov/ontario-design-system-component-library-react';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import useBaseUrl from '@docusaurus/useBaseUrl';

# ontario-header

Use the `ontario` type header for all pages that are part of the main ontario.ca website. This header is mandatory.

Use the `application` type header for applications and subsites outside of the main ontario.ca website.

Use the `serviceOntario` type header for ServiceOntario sites/apps. This type is for use by ServiceOntario teams only.

## Usage guidance

Please refer to the [Ontario Design System Ontario.ca header](https://designsystem.ontario.ca/components/detail/ontario-header.html) for current documentation guidance for the Ontario.ca header.

Please refer to the [Ontario Design System Application header](https://designsystem.ontario.ca/components/detail/application-header.html) for current documentation guidance for the Application header.

Please refer to the [Ontario Design System ServiceOntario header](https://designsystem.ontario.ca/components/detail/service-ontario-header.html) for current documentation guidance for the ServiceOntario header.

## Configuration

Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the header component can be added directly into the project's code, and can be customized by updating the properties outlined [here](#properties). Additional information on custom types for header properties are outlined [here](#custom-property-types). Please see the [examples](#examples) below for how to configure the component.

## Examples

Example of an Ontario.ca header component.

```mdx-code-block
<Tabs
	defaultValue="html"
	values={[
		{label: 'HTML', value: 'html'},
		{label: 'React', value: 'react'},
		{label: 'Angular', value: 'angular'},
	]}
	groupId="framework"
	queryString="framework">
<TabItem value="html">
```

```html
<ontario-header
	type="ontario"
	language-toggle-options='{
		"englishLink": "/driving-and-roads",
		"frenchLink" : "/fr/conduite-et-routes"
	}'
	menu-items='[
		{
			"title": "Arts and Culture",
			"href": "https://www.ontario.ca/page/arts-and-culture",
			"linkIsActive": "false"  
		},
		{
			"title": "Business and economy",
			"href": "https://www.ontario.ca/page/business-and-economy",
			"linkIsActive": "false"  
		},
		{
			"title": "Driving and Roads",
			"href": "https://www.ontario.ca/page/driving-and-roads",
			"linkIsActive": "false"  
		},
		{
			"title": "Education and training",
			"href": "https://www.ontario.ca/page/education-and-training",
			"linkIsActive": "false"  
		},
		{
			"title": "Environment and energy",
			"href": "https://www.ontario.ca/page/environment-and-energy",
			"linkIsActive": "false"  
		},
		{
			"title": "Government",
			"href": "https://www.ontario.ca/page/government",
			"linkIsActive": "false"  
		},
		{
			"title": "Health and wellness",
			"href": "https://www.ontario.ca/page/health-care-ontario",
			"linkIsActive": "false"  
		},
		{
			"title": "Home and community",
			"href": "https://www.ontario.ca/page/home-and-community",
			"linkIsActive": "false"  
		},
		{
			"title": "Jobs and employment",
			"href": "https://www.ontario.ca/page/jobs-and-employment",
			"linkIsActive": "false"  
		},
		{
			"title": "Law and safety",
			"href": "https://www.ontario.ca/page/law-and-safety",
			"linkIsActive": "false"  
		},
		{
			"title": "Rural and north",
			"href": "https://www.ontario.ca/page/rural-and-north",
			"linkIsActive": "false"  
		},
		{
			"title": "Taxes and benefits",
			"href": "https://www.ontario.ca/page/taxes-and-benefits",
			"linkIsActive": "false"  
		},
		{
			"title": "Travel and recreation",
			"href": "https://www.ontario.ca/page/travel-and-recreation",
			"linkIsActive": "false"  
		}
	]'
>
</ontario-header>
```

```mdx-code-block
</TabItem>
<TabItem value="react">
```

```tsx
<OntarioHeader
	type="ontario"
	languageToggleOptions={{
		englishLink: '/driving-and-roads',
		frenchLink: '/fr/conduite-et-routes',
	}}
	menuItems={[
		{ title: 'Arts and Culture', href: 'https://www.ontario.ca/page/arts-and-culture', linkIsActive: false },
		{ title: 'Business and economy', href: 'https://www.ontario.ca/page/business-and-economy', linkIsActive: false },
		{ title: 'Driving and Roads', href: 'https://www.ontario.ca/page/driving-and-roads', linkIsActive: false },
		{
			title: 'Education and training',
			href: 'https://www.ontario.ca/page/education-and-training',
			linkIsActive: false,
		},
		{
			title: 'Environment and energy',
			href: 'https://www.ontario.ca/page/environment-and-energy',
			linkIsActive: false,
		},
		{ title: 'Government', href: 'https://www.ontario.ca/page/government', linkIsActive: false },
		{ title: 'Health and wellness', href: 'https://www.ontario.ca/page/health-care-ontario', linkIsActive: false },
		{ title: 'Home and community', href: 'https://www.ontario.ca/page/home-and-community', linkIsActive: false },
		{ title: 'Jobs and employment', href: 'https://www.ontario.ca/page/jobs-and-employment', linkIsActive: false },
		{ title: 'Law and safety', href: 'https://www.ontario.ca/page/law-and-safety', linkIsActive: false },
		{ title: 'Rural and north', href: 'https://www.ontario.ca/page/rural-and-north', linkIsActive: false },
		{ title: 'Taxes and benefits', href: 'https://www.ontario.ca/page/taxes-and-benefits', linkIsActive: false },
		{ title: 'Travel and recreation', href: 'https://www.ontario.ca/page/travel-and-recreation', linkIsActive: false },
	]}
></OntarioHeader>
```

```mdx-code-block
</TabItem>
<TabItem value="angular">
```

```html
<ontario-header
	[type]="'ontario'"
	[languageToggleOptions]="{ englishLink: '/driving-and-roads', frenchLink: '/fr/conduite-et-routes' }"
	[menuItems]="[
		{ title: 'Arts and Culture', href: 'https://www.ontario.ca/page/arts-and-culture', linkIsActive: false },
		{ title: 'Business and economy', href: 'https://www.ontario.ca/page/business-and-economy', linkIsActive: false },
		{ title: 'Driving and Roads', href: 'https://www.ontario.ca/page/driving-and-roads', linkIsActive: false },
		{ title: 'Education and training', href: 'https://www.ontario.ca/page/education-and-training', linkIsActive: false },
		{ title: 'Environment and energy', href: 'https://www.ontario.ca/page/environment-and-energy', linkIsActive: false },
		{ title: 'Government', href: 'https://www.ontario.ca/page/government', linkIsActive: false },
		{ title: 'Health and wellness', href: 'https://www.ontario.ca/page/health-care-ontario', linkIsActive: false },
		{ title: 'Home and community', href: 'https://www.ontario.ca/page/home-and-community', linkIsActive: false },
		{ title: 'Jobs and employment', href: 'https://www.ontario.ca/page/jobs-and-employment', linkIsActive: false },
		{ title: 'Law and safety', href: 'https://www.ontario.ca/page/law-and-safety', linkIsActive: false },
		{ title: 'Rural and north', href: 'https://www.ontario.ca/page/rural-and-north', linkIsActive: false },
		{ title: 'Taxes and benefits', href: 'https://www.ontario.ca/page/taxes-and-benefits', linkIsActive: false },
		{ title: 'Travel and recreation', href: 'https://www.ontario.ca/page/travel-and-recreation', linkIsActive: false }
	]"
></ontario-header>
```

```mdx-code-block
</TabItem>
</Tabs>
```

<div>
	<OntarioHeader
		assetBasePath={useBaseUrl("/assets")}
		type="application"
		disableDynamicMenu="true"
		applicationHeaderInfo={{
			title: "Driving and roads",
			href: "/driving-and-roads",
			maxSubheaderLinks: {
				desktop: 1,
				tablet: 1,
			},
		}}
		languageToggleOptions={{
			englishLink: "/",
			frenchLink: "/fr",
		}}
		menuItems={[
			{
				title: "Vehicle registration",
				href: "/vehicle-registration",
				linkIsActive: false,
			},
			{
				title: "Driver records",
				href: "/driver-records",
				linkIsActive: false,
			},
			{
				title: "Accessible Parking Permits",
				href: "/accessible-parking-permits",
				linkIsActive: true,
			},
			{
				title: "Highway traveler information",
				href: "/highway-traveler-information",
				linkIsActive: false,
			},
		]}
	></OntarioHeader>
</div>

Example of an Application header component.

```mdx-code-block
<Tabs
	defaultValue="html"
	values={[
		{label: 'HTML', value: 'html'},
		{label: 'React', value: 'react'},
		{label: 'Angular', value: 'angular'},
	]}
	groupId="framework"
	queryString="framework">
<TabItem value="html">
```

```html
<ontario-header
	type="application"
	disable-dynamic-menu="true"
	application-header-info='{
		"title": "Driving and roads",
		"href": "/driving-and-roads",
		"title": "Driving and roads",
		"href": "/driving-and-roads",
		"maxSubheaderLinks": "{
			"desktop": "3",
			"tablet": "1"
		}"
	}'
	language-toggle-options='{
		"englishLink": "/",
		"frenchLink" : "/fr"
	}'
	menu-items='[
		{ 
			"title": "Vehicle registration", 
			"href": "/vehicle-registration",
			"linkIsActive": "false" 
		},
		{ 
			"title": "Driver records", 
			"href": "/driver-records",
			"linkIsActive": "false"  
		}, 
		{ 
			"title": "Accessible Parking Permits",
			"href": "/accessible-parking-permits",
			"linkIsActive": "false"  
		},
		{ 
			"title": "Highway traveler information", 
			"href": "/highway-traveler-information",
			"linkIsActive": "true"
		}
	]'
	custom-language-toggle="{changeLanguage}"
>
</ontario-header>

<script>
	const changeLanguage = (e: Event) => {
		e.preventDefault();
		// Logic to change language below
	};
</script>
```

```mdx-code-block
</TabItem>
<TabItem value="react">
```

```tsx
const changeLanguage = (event: Event) => {
	event.preventDefault();
	// Logic to change language below
};

<OntarioHeader
	assetBasePath={useBaseUrl('/assets')}
	type="application"
	disableDynamicMenu={true}
	applicationHeaderInfo={{
		title: 'Driving and roads',
		href: '/driving-and-roads',
		maxSubheaderDesktopLinks: 3,
		maxSubheaderTabletLinks: 1,
	}}
	languageToggleOptions={{
		englishLink: '/',
		frenchLink: '/fr',
	}}
	menuItems={[
		{ title: 'Vehicle registration', href: '/vehicle-registration', linkIsActive: false },
		{ title: 'Driver records', href: '/driver-records', linkIsActive: false },
		{ title: 'Accessible Parking Permits', href: '/accessible-parking-permits', linkIsActive: false },
		{
			title: 'Highway traveler information',
			href: '/highway-traveler-information',
			linkIsActive: true,
			onClickHandler: (e) => {
				e.preventDefault();
				alert('Menu item clicked!');
			},
		},
	]}
	customLanguageToggle={changeLanguage}
></OntarioHeader>;
```

```mdx-code-block
</TabItem>
<TabItem value="angular">
```

```html
<ontario-header
	[assetBasePath]="'/assets'"
	[type]="'application'"
	[disableDynamicMenu]="true"
	[applicationHeaderInfo]="{
		title: 'Driving and roads',
		href: '/driving-and-roads',
		maxSubheaderDesktopLinks: 3,
		maxSubheaderTabletLinks: 1
	}"
	[languageToggleOptions]="{ englishLink: '/', frenchLink: '/fr' }"
	[menuItems]="[
		{ title: 'Vehicle registration', href: '/vehicle-registration', linkIsActive: false },
		{ title: 'Driver records', href: '/driver-records', linkIsActive: false },
		{ title: 'Accessible Parking Permits', href: '/accessible-parking-permits', linkIsActive: false },
		{
			title: 'Highway traveler information',
			href: '/highway-traveler-information',
			linkIsActive: true,
			onClickHandler: onMenuClick
		}
	]"
	[customLanguageToggle]="changeLanguage"
></ontario-header>
```

```ts
onMenuClick(event: Event): void {
	event.preventDefault();
	alert('Menu item clicked!');
}

changeLanguage(event: Event): void {
	event.preventDefault();
	// Logic to change language below
}
```

```mdx-code-block
</TabItem>
</Tabs>
```

<div>
	<OntarioHeader
		assetBasePath={useBaseUrl('/assets')}
		type="application"
		disableDynamicMenu={true}
		applicationHeaderInfo={{
			title: 'Driving and roads',
			href: '/driving-and-roads',
			maxSubheaderDesktopLinks: 3,
			maxSubheaderTabletLinks: 1,
		}}
		languageToggleOptions={{
			englishLink: '/',
			frenchLink: '/fr',
		}}
		menuItems={[
			{ title: 'Vehicle registration', href: '/vehicle-registration', linkIsActive: false },
			{ title: 'Driver records', href: '/driver-records', linkIsActive: false },
			{ title: 'Accessible Parking Permits', href: '/accessible-parking-permits', linkIsActive: false },
			{
				title: 'Highway traveler information',
				href: '/highway-traveler-information',
				linkIsActive: true,
				onClickHandler: (e) => {
					e.preventDefault();
					alert('Menu item clicked!');
				},
			},
		]}>
	 </OntarioHeader>
</div>

## Custom property types

### languageToggleOptions

```html
language-toggle-options='{ "englishLink": "/en", "frenchLink": "/fr" }'
```

| **Property name** | **Type** | **Description**                   |
| ----------------- | -------- | --------------------------------- |
| `englishLink`     | `string` | The URL link for the English page |
| `frenchLink`      | `string` | The URL link for the French page  |

### menuItems

For the Ontario.ca header, the menu items will automatically be rendered in a dropdown menu button.

If `maxSubheaderLinks` is set within `applicationHeaderInfo` on the `ontario-header` component for an `application` type header, some of these links will be dispersed as links within the subheader menu bar relative to the breakpoint and number set.

```html
<ontario-header
	menu-items='[ 
		{ 
			"title": "Vehicle registration",
			"href": "/vehicle-registration",
			"linkIsActive": "false" 
		}, 
		{ 
			"title": "Driver records",
			"href": "/driver-records", 
			"linkIsActive": "false" 
		}, 
		{ 
			"title": "Accessible Parking Permits", 
			"href": "/accessible-parking-permits", 
			"linkIsActive": "false" 
		}, 
		{ 
			"title": "Highway traveler information", 
			"href": "/highway-traveler-information", 
			"linkIsActive": "true",
			"onClickHandler": (e: Event) => { e.preventDefault(); alert("Menu item clicked!") }
		} 
	]'
></ontario-header>
```

| **Property name** | **Type**                 | **Description**                                                                                                                                     |
| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`           | `string`                 | The title of the menu item (this is what will appear as the label in the header/dropdown menu)                                                      |
| `href`            | `string`                 | The URL for the menu item                                                                                                                           |
| `linkIsActive`    | `boolean`                | A boolean flag for whether or not the current menu item link is active. If set to true, active classes and styles will be applied to the menu item. |
| `onClickHandler`  | `(event: Event) => void` | An optional custom function to add to the menu item. This can be used if any additional logic should happen when the menu item is clicked.          |

### applicationHeaderInfo

Note that this is only required for the Application and ServiceOntario header types.

```html
application-header-info='{ "title": "Application name", "href": "/", "maxSubheaderLinks": {"desktop": "4", "tablet":
"2", "mobile": "1"}}'
```

| Property name       | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`             | `string` | The title of the application (this is what will appear as the label for the application sub header title)                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `href`              | `string` | The URL for the application name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `maxSubheaderLinks` | `number` | The number of links to appear in the Ontario application type header's subheader. This is optional.<br /><br /> These links will display in the order they are described in the `menuItems` prop. For example, if the `maxSubheaderLinks.desktop` number is '4', the first four `menuItems` items will appear in the application subheader on desktop, and the rest will appear in the menu dropdown.<br /><br /> If no dropdown item is needed, the `maxSubheaderLinks` number should match the `menuItems` items length. |

## Accessibility

### Application header

To ensure best practices, it is important to limit the number of navigation links passed to the `menuItems` property. We recommend a maximum of seven links, and to keep the labels for these links concise.

## Custom event types

### HeaderMenuToggleDetail

Payload shape used by the `menuButtonToggled` custom event.

```ts
interface HeaderMenuToggleDetail {
	isOpen: boolean;
	trigger: 'click' | 'keyboard' | 'programmatic';
}
```

| Property name | Type                                      | Description                                       |
| ------------- | ----------------------------------------- | ------------------------------------------------- |
| `isOpen`      | `boolean`                                 | Whether the menu is open after the toggle action. |
| `trigger`     | `'click' \| 'keyboard' \| 'programmatic'` | How the toggle was triggered.                     |

## Technical Note: SSR (Server-Side Rendering) Considerations

The Ontario Header component supports server-side rendering, with a few important limitations:

- **Hydrated-only menu fetching:** Dynamic menu fetching through `fetchOntarioMenu` is browser-only and will not execute during SSR.
- **Language prop:** Pass `language` explicitly during SSR. Runtime language detection via `document.documentElement.lang` and `window` is hydrated-only.
- **Hydrated-only interactions:** Interactive state such as `menuToggle` and `searchToggle` requires JavaScript and is unavailable before hydration.
- **Framework guidance:** For SSR-critical applications, prefer static `menuItems` and only enable dynamic menu fetching in guaranteed client-side contexts.

<!-- Auto Generated Below -->

## Overview

Ontario Header renders Ontario.ca, application, and ServiceOntario header variants.

For component guidance, see:

- https://designsystem.ontario.ca/components/detail/ontario-header.html
- https://designsystem.ontario.ca/components/detail/application-header.html
- https://designsystem.ontario.ca/components/detail/service-ontario-header.html
- https://designsystem.ontario.ca/developer-docs/components/ontario-header/

## Properties

| Property                | Attribute                 | Description                                                                                                                                                                                                                                                                                                                                                                                                        | Type                                                          | Default         |
| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | --------------- |
| `applicationHeaderInfo` | `application-header-info` | Information pertaining to the application and ServiceOntario headers. For the 'application' header type, this includes the application name, URL and optional props for the number of links in the subheader for desktop, tablet, and mobile views. For the 'serviceOntario' header type, the 'title' property is used as the service name displayed in the subheader.                                             | `ApplicationHeaderInfo \| string`                             | `undefined`     |
| `assetBasePath`         | `asset-base-path`         | The base path to an assets folder containing the Design System assets                                                                                                                                                                                                                                                                                                                                              | `string`                                                      | `undefined`     |
| `customLanguageToggle`  | `custom-language-toggle`  | A custom function to pass to the language toggle button.                                                                                                                                                                                                                                                                                                                                                           | `((event: Event) => void) \| undefined`                       | `undefined`     |
| `customSignInToggle`    | `custom-sign-in-toggle`   | A custom function to pass to the sign-in button.                                                                                                                                                                                                                                                                                                                                                                   | `((event: Event) => void) \| undefined`                       | `undefined`     |
| `disableDynamicMenu`    | `disable-dynamic-menu`    | Option to disable fetching of the dynamic menu from the Ontario Header API. When set to true, the static `menuItems` prop will be used instead of fetching from the API. When set to false (default), menu items are fetched dynamically from the Ontario Header API endpoint. This property only applies to the 'ontario' header type. The 'application' and 'serviceOntario' types always use static menu items. | `boolean`                                                     | `false`         |
| `language`              | `language`                | The language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If none is passed, it will default to English.                                                                                                                                                                                                       | `"en" \| "fr" \| undefined`                                   | `'en'`          |
| `languageToggleOptions` | `language-toggle-options` | Information pertaining to the language toggle links.                                                                                                                                                                                                                                                                                                                                                               | `LanguageToggleOptions \| string \| undefined`                | `undefined`     |
| `menuItems`             | `menu-items`              | The items that will go inside the menu dropdown. For the 'ontario' header type, these items are displayed in the overflow menu. If `disableDynamicMenu` is false, static items will be overridden by dynamically fetched items from the Ontario Header API. For the 'application' and 'serviceOntario' header types, these items are displayed in the subheader menu and overflow menu.                            | `MenuItem[] \| string`                                        | `undefined`     |
| `signInMenuItems`       | `sign-in-menu-items`      | Information pertaining to the sign-in menu items for the Ontario header.                                                                                                                                                                                                                                                                                                                                           | `MenuItem[] \| string \| undefined`                           | `undefined`     |
| `type`                  | `type`                    | The type of header.                                                                                                                                                                                                                                                                                                                                                                                                | `"application" \| "ontario" \| "serviceOntario" \| undefined` | `'application'` |

## Events

| Event               | Description                                                                                                                                                                              | Type                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `menuButtonToggled` | This event is toggled when the menu button is pressed. The `<ontario-header-overflow-menu>` sub-component listens for this event To trigger the showing and hiding of the overflow menu. | `CustomEvent<HeaderMenuToggleDetail>` |

## Dependencies

### Depends on

- [ontario-language-toggle](../ontario-language-toggle)
- [ontario-header-menu-tabs](../ontario-header-menu-tabs)
- [ontario-header-overflow-menu](../ontario-header-overflow-menu)

### Graph

```mermaid
graph TD;
  ontario-header --> ontario-language-toggle
  ontario-header --> ontario-header-menu-tabs
  ontario-header --> ontario-header-overflow-menu
  ontario-header-menu-tabs --> ontario-header-overflow-menu
  style ontario-header fill:#f9f,stroke:#333,stroke-width:4px
```

---

_Built with [StencilJS](https://stenciljs.com/)_