Month Picker

Accessible, unstyled grid of the twelve months of a year with year paging.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { MonthPicker } from "@vizejs/ui/month-picker";

Or copy the source into your project with vize lib pull month-picker (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Month picker bound with v-model, a fixed SSR-safe today, and a selectable range. -->
<script setup lang="ts">
import { ref } from "vue";

import { formatIsoYearMonth, MonthPicker } from "@vizejs/ui/month-picker";
import type { PlainYearMonth } from "@vizejs/ui/month-picker";

const billing = ref<PlainYearMonth | null>({ year: 2026, month: 10 });
</script>

<template>
  <div>
    <MonthPicker
      v-model="billing"
      name="billing-month"
      locale="en-US"
      aria-label="Billing month"
      :today="{ year: 2026, month: 10, day: 1 }"
      :min="{ year: 2025, month: 1 }"
      :max="{ year: 2027, month: 12 }"
    />
    <output>{{ billing ? formatIsoYearMonth(billing) : "No month" }}</output>
  </div>
</template>

API

MonthPicker

Source: src/families/date-time/month-picker/month-picker.vue

Props

Events

Slots

Behavior

Normative state x input -> outcome table for month-picker.vue (@vizejs/ui/month-picker), a grid of the twelve months of one year built on the shared linear period grid (period-grid-runtime.ts). Every row is proven by the named test.

SSR determinism follows calendar.behavior.md: pass today or now + timeZone, or a value, to render a complete grid on the server. Parts: root, header, previous, heading, next, grid, row, cell, month.