npm package: @highlight-ui/month-navigation
Description: Month/Year navigation component
Author: Personio GmbH & Co. KG
Latest version: 3.5.0

[![npm](https://img.shields.io/npm/v/@highlight-ui/month-navigation)](https://www.npmjs.com/package/@highlight-ui/month-navigation)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/v/0/p/045b58-month-navigation/b/93935a)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/navigation-monthnavigation--default)

# @highlight-ui/month-navigation

Using npm:

```bash
npm install @highlight-ui/month-navigation
```

Using yarn:

```bash
yarn add @highlight-ui/month-navigation
```

Using pnpm:

```bash
pnpm install @highlight-ui/month-navigation
```

In your (S)CSS file:

```scss
@import url('@highlight-ui/month-navigation');
```

Once the package is installed, you can import the library:

```ts
import { MonthNavigation } from '@highlight-ui/month-navigation';
```

## Usage

```tsx
import React from 'react';
import { MonthNavigation } from '@highlight-ui/month-navigation';

export default function MonthNavigationExample() {
  return <MonthNavigation locale="en-GB" />;
}
```

## Props 📜

> The MonthNavigation props build upon the [ReactDatePicker](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/month-navigation/src/ReactDatePickerRaw/ReactDatePickerRaw.tsx?ref_type=heads#L9) props

| Prop                       | Type                        | Required | Default  | Description                                                                                                         |
| :------------------------- | :-------------------------- | :------- | :------- | :------------------------------------------------------------------------------------------------------------------ |
| `size`                     | `'small', 'medium'`         | No       | `medium` | Size variant of the component                                                                                       |
| `onFocus`                  | `() => void`                | No       |          | Callback to be called when the navigation input receives a focus event                                              |
| `onBlur`                   | `() => void`                | No       |          | Callback to be called when the navigation input receives a blur event                                               |
| `monthSelectPluginOptions` | `TMonthSelectPluginOptions` | No       |          | Options that will be passed to Flatpickr's [monthSelectPlugin](https://flatpickr.js.org/plugins/#monthselectplugin) |
| `showTodayButton`          | `boolean`                   | No       | `true`   | Whether or not to display the current month button                                                                  |
| `todayText`                | `string`                    | No       | `Today`  | Will be rendered as the trigger to navigate to current IRL month                                                    |
| `className`                | `string`                    | No       |          | Allows providing a custom class name to the DIV element that surrounds the text                                     |

### Custom types 🔠

| Type                        | Values                                                                                                                                                                         | Description                                 |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
| `TMonthSelectPluginOptions` | ["TMonthSelectPluginOptions"](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/month-navigation/src/MonthNavigation.tsx#L24) props | Used in the `monthSelectPluginOptions` prop |

## Keyboard Navigation ⌨️

Here are the keyboard shortcuts to help navigate through the month navigation. These keys allow for smooth accessibility and interaction with the month selection:

### General Navigation
| Key (Mac Shortcut)     | Function                                                                                                 |
|------------------------|----------------------------------------------------------------------------------------------------------|
| `Tab` (`Tab`)          | Focus on month navigation components (arrows, trigger and 'Today' button) |
| `Escape` (`Escape`)    | Close the month navigation and return focus to the input trigger.                                            |

### Within Month navigation
| Key (Mac Shortcut)     | Function                                                                                                 |
|------------------------|----------------------------------------------------------------------------------------------------------|
| `Home` (`fn` + `←`)    | Focus on the first month (January) of the current year.                                                  |
| `End` (`fn` + `→`)     | Focus on the last month (December) of the current year.                                                  |
| `PageUp` (`fn` + `↑`)  | Navigate to the previous year.                                                                           |
| `PageDown` (`fn` + `↓`)| Navigate to the next year.                                                                               |
| `Up Arrow` (`↑`)       | Move focus up by 4 months. If focused month is on the top most row, navigate to the corresponding month in the previous year. |
| `Down Arrow` (`↓`)     | Move focus down by 4 months. If focused is on the last row, navigate to the corresponding month in the next year. |
| `Right Arrow` (`→`)    | Move to the next month. If focused on the last month, navigate to the first month of the next year.       |
| `Left Arrow` (`←`)     | Move to the previous month. If focused on the first month, navigate to the last month of the previous year. |

Note: When the month navigation is blurred, the focus returns to the input trigger.


## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/045b58-month-navigation/b/93935a) for usage guidelines and visual examples.

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).