vue-month-picker

vue-month-picker

A lightweight, dependency-free month picker component for Vue 3 with TypeScript support.

---

Features

• Zero runtime dependencies
• TypeScript-first (<script setup> + Composition API)
• Inline picker (MonthPicker) and input-driven picker (MonthPickerInput)
• Range selection
• minDate / maxDate constraints
• Configurable dateFormat tokens
• Dark theme
• Year-only mode
• Clearable selection
• 45+ built-in languages

---

Installation

npm install vue-month-picker

yarn add vue-month-picker

---

Quick start

Register globally

import { createApp } from 'vue'
import App from './App.vue'
import VueMonthPicker from 'vue-month-picker'

createApp(App).use(VueMonthPicker).mount('#app')

Register locally

<script setup lang="ts">
import { MonthPicker, MonthPickerInput } from 'vue-month-picker'
import type { IDateResult } from 'vue-month-picker'

const onDateChange = (date: IDateResult) => {
  console.log(date.month, date.year)
}
</script>

<template>
  <MonthPicker @change="onDateChange" />
</template>

---

Usage examples

Inline picker

<script setup lang="ts">
import { ref } from 'vue'
import { MonthPicker } from 'vue-month-picker'
import type { IDateResult } from 'vue-month-picker'

const date = ref<IDateResult | null>(null)
</script>

<template>
  <MonthPicker @change="date = $event" />
  <p v-if="date">{{ date.month }} {{ date.year }}</p>
</template>

Input-driven picker

<script setup lang="ts">
import { MonthPickerInput } from 'vue-month-picker'
</script>

<template>
  <MonthPickerInput
    :no-default="true"
    date-format="%n %Y"
    placeholder="Select a month"
  />
</template>

Pre-filled input with a reactive default

<script setup lang="ts">
import { ref } from 'vue'
import { MonthPickerInput } from 'vue-month-picker'

const month = ref(new Date().getMonth() + 1)
const year = ref(new Date().getFullYear())
</script>

<template>
  <MonthPickerInput
    :input-pre-filled="true"
    :default-month="month"
    :default-year="year"
    date-format="%n, %Y"
  />
</template>

With min/max date constraints

<template>
  <MonthPicker
    :min-date="new Date(2024, 0, 1)"
    :max-date="new Date(2024, 11, 31)"
    :default-year="2024"
    :default-month="6"
    @change="onDateChange"
  />
</template>

Range selection

<template>
  <MonthPicker
    :range="true"
    :no-default="true"
    @change="onRangeChange"
  />
</template>

Dark theme

<template>
  <MonthPicker variant="dark" />
</template>

---

API

MonthPicker and MonthPickerInput share the same props and events.

Props

Prop	Type	Default	Description
lang	String	"en"	Language code for month names. See supported languages.
months	String[]	—	Override month names with a custom 12-element array.
default-month	Number	—	Initially selected month (1–12). Omit or use no-default to start unselected.
default-year	Number	current	Initially displayed year.
no-default	Boolean	false	Start with no month selected.
show-year	Boolean	true	Show the year header with navigation arrows.
editable-year	Boolean	false	Render the year as a text input instead of a label.
clearable	Boolean	false	Allow clicking the selected month again to deselect it.
variant	String	"default"	Color theme — "default" or "dark".
year-only	Boolean	false	Hide months and act as a pure year picker.
min-date	Date	null	Months before this date are disabled.
max-date	Date	null	Months after this date are disabled.
range	Boolean	false	Enable two-click range selection.
default-month-range	[Number, Number]	null	Default range as [fromIndex, toIndex] (0-based).
date-format	String	"%n, %Y"	Format string for the MonthPickerInput display value. See tokens.
input-pre-filled	Boolean	false	(MonthPickerInput only) Pre-fill the input on mount using default-month and default-year.
placeholder	String	null	(MonthPickerInput only) Input placeholder text.
highlight-exact-date	Boolean	false	Only highlight the selected cell when both month and year match.

date-format tokens

Token	Output	Example
%n	Full month name	January
%m	Zero-padded month number	01
%M	Unpadded month number	1
%Y	4-digit year	2024
%y	2-digit year	24

"%n, %Y"  →  January, 2024
"%m/%Y"   →  01/2024
"%M/%y"   →  1/24
"%n %y"   →  January 24

Events

Event	Payload	Description
@change	IDateResult	Fires whenever the selected value changes, including on mount when a default is set.
@input	IDateResult	Fires only on explicit user interaction. Prefer this over @change for form bindings.
@change-year	Number	Fires when the user navigates to a different year.
@clear	—	Fires when the user clears the selection (requires clearable).

IDateResult

interface IDateResult {
  from: Date          // first day of the selected month
  to: Date            // last day of the selected month
  month: string       // full month name in the selected language
  monthIndex: number  // 1-based month number
  year: number

  // Range mode only
  rangeFrom?: number       // 0-based start index
  rangeTo?: number         // 0-based end index
  rangeFromMonth?: string  // month name at range start
  rangeToMonth?: string    // month name at range end
}

---

Languages

45+ locales are built in. Pass the ISO code to the lang prop:

Code	Language	Code	Language	Code	Language
af	Afrikaans	it	Italian	ru	Russian
ar	Arabic	ja	Japanese	sk	Slovak
bg	Bulgarian	km	Khmer	sl	Slovenian
cs	Czech	ko	Korean	so	Somali
da	Danish	ku	Kurdish	sq	Albanian
de	German	lt	Lithuanian	sr	Serbian
el	Greek	lv	Latvian	sv	Swedish
en	English	ms	Malay	th	Thai
es	Spanish	ne	Nepali	tr	Turkish
et	Estonian	nl	Dutch	uk	Ukrainian
fi	Finnish	no	Norwegian	ur	Urdu
fr	French	pa	Punjabi	vi	Vietnamese
he	Hebrew	pl	Polish	yi	Yiddish
hi	Hindi	pt	Portuguese	zh	Chinese
hr	Croatian	is	Icelandic	zu	Zulu
hu	Hungarian	id	Indonesian

Language missing? Open a PR adding a row to src/languages.ts, or pass a custom months array:

<MonthPicker :months="['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']" />

---

Development

# Install dependencies
npm install

# Start dev server (App.vue playground)
npm run dev

# Type-check + build library
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

---

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push: git push origin my-feature
5. Open a pull request

---

License

MIT