# Month Picker
Allows users to select a month and year, either by typing it directly or by choosing from a popup of a year header and a twelve-month grid.
Part of the Harmonia Alpine.js component library. Every directive uses the `x-h-` prefix.
## Usage
Use the Month Picker when a field represents a whole month (a reporting period, a billing month, a statement month) rather than a specific day. For a specific day use the Date Picker instead.
## Directives
`x-h-month-picker` is the root. The directives compose one component and must be nested as shown in the Examples below (the library throws at runtime when a required ancestor is missing):
- `x-h-month-picker`
- `x-h-month-picker-trigger`
- `x-h-month-picker-popup`
## API
### Attributes
#### x-h-month-picker
| Attribute | Values | Required | Description |
| --------- | ------------------ | -------- | ------------------------------------- |
| data-size | `sm`
`default` | false | Changes the size of the month picker. |
#### x-h-month-picker-popup
| Attribute | Values | Required | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------- |
| data-align | `bottom-start`
`bottom`
`bottom-end`
`right-start`
`right`
`right-end`
`left-start`
`left`
`left-end`
`top-start`
`top`
`top-end` | false | Aligns the popup relative to the picker trigger. |
| data-aria-prev-year | string | false | Sets the `aria-label` attribute value for the previous year button. |
| data-aria-next-year | string | false | Sets the `aria-label` attribute value for the next year button. |
### Modifiers
| Modifier | Description |
| -------- | ------------------------------------ |
| table | Use when the input is inside a table |
### Configuration
You can pass a configuration object to the popup as an expression or as a value.
| Key | Description |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| locale | The locale of the month names as a BCP 47 language tag. If not provided, it is taken from the page's `` attribute, then the browser locale. |
Some locales, such as `bg-BG`, conventionally abbreviate months numerically, so the popup grid shows numbers there. The text input is unaffected because it uses the full month name.
### Model
The month picker reads and writes months as `YYYY-MM` strings (e.g. `"2025-06"`). The text input displays the month using the user's locale (e.g. "June 2025"). The model value is unaffected by the display format.
To clear the value, delete the text in the input, click the already selected month in the popup, or set the bound model to an empty string.
### Events
| Event | Description |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| change | Fired on the inner input when the user picks a month from the popup or types a valid month. The event bubbles, so a listener can be placed on the `x-h-month-picker` element. Read the new value from the bound model, as the input's own value holds the formatted display text instead. |
There is no need to use `$watch` to react to user selection - listen for `change` instead. See Listening for changes.
### Validation timing
By default this control shows native-constraint errors (for example `required`) only after the user interacts with it or attempts to submit, not on page load. To validate on load instead, set `data-validate="immediate"` on a wrapping `x-h-fieldset`, `x-h-field`, or any ancestor element. Setting `aria-invalid="true"` yourself always shows the error immediately. See Fieldset for details.
## Keyboard Handling
The user can use the following keyboard shortcuts in order to navigate through the month picker:
- `Enter` / `Space` - Opens the popup, or selects the focused month when open. Pressing it on the already selected month deselects it and clears the value.
- `Left` / `Right` - Moves focus to the previous/next month, crossing into the previous/next year from January/December.
- `Up` / `Down` - Moves focus one row (three months) up/down.
- `Home` / `End` - Moves focus to January/December of the shown year.
- `PageUp` / `PageDown` - Moves focus to the same month of the previous/next year.
- `Esc` - Closes the popup.
## Binding
Binds through Alpine `x-model`. See the Examples for the expected value shape.
## Examples
```html
```
### Listening for changes
```html
```
### With locale
```html
```
### Invalid
Reacts to the native invalid state or to the `aria-invalid` attribute.
```html
```
### Disabled
Set the native `disabled` attribute on the inner input to disable the whole picker.
```html
```
### Read-only
Set the native `readonly` attribute on the inner input. The value is shown with a muted background, and neither typing nor the popup can change it.
```html
```
Full docs: https://www.codbex.com/harmonia/components/month-picker.html
## Notes
- Directive values are Alpine expressions, so quote string literals: `x-h-...="'Label'"`.
- Components render only after Alpine has registered Harmonia. See SKILL.md for setup.