Month Year Picker

The month year picker allows users to select a month and year from a calendar-style interface.

Basic Usage

/

Property Value:

<template>
  <mc-month-year-picker id="monthyearpicker" v-model="monthYearPickerModel" display-helper />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');
</script>

Adding Label

Select Month and Year

/

Value: 09-1997

Property Value: 09-1997

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Select Month and Year"
    display-helper
    format="MM-YYYY"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');
</script>

Custom Component

You can use the default slot to use any component as the month year picker input or to change the format of the rendered date without changing the format of the date model.

Custom Month Year Picker Input

monthYearPickerModel:
monthYearPickerInputModel:

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Custom Month Year Picker Input"
    display-helper
    format="MMM-YYYY"
    @update:model-value="handleMonthYearPickerModelChange"
  >
    <template #default="{ handleClick }">
      <mc-input
        v-model="monthYearPickerInputModel"
        readonly
        class="mc-w-full mc-cursor-pointer"
        placeholder="MMM / YYYY"
        @click="handleClick"
      >
        <template #icon>
          <Icon icon="ph:calendar-blank" />
        </template>
      </mc-input>
    </template>
  </mc-month-year-picker>
</template>

<script lang="ts" setup>
import { ref } from 'vue';
import dayjs from 'dayjs';

const monthYearPickerModel = ref('');
const monthYearPickerInputModel = ref('');

const handleMonthYearPickerModelChange = (newValue: string) => {
  monthYearPickerInputModel.value = dayjs(newValue).format('MMM / YYYY').toUpperCase();
};
</script>

Custom Width

You can manually set the width of the month year picker by passing the width prop.

Month Year Picker

/

Property Value:

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    width="400px"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');
</script>

Date Format

You can specify the format of the month-year by passing the format prop. The default format is MM-YYYY. The component will return dates in the specified format.

Month Year Picker

/

Value:

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year with YYYY-MM format"
    format="YYYY-MM"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');
</script>

Month Year with MMMM YYYY format

/

Value:

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year with MMMM YYYY format"
    format="MMMM YYYY"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');
</script>

Disabled

Add the disabled prop to disable the month year picker.

Month Year Picker

/

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    display-helper
    disabled
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');
</script>

Read Only

Add the readonly prop to make month year picker as read only.

Month Year Picker

/

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    display-helper
    readonly
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('10-2025');
</script>

Helper Text

A helper message is a text label displayed below the input field, offering additional information such as instructions, formatting tips, or validation feedback.

To display the helper message, set the display-helper prop to true and add the helper-text prop with the message content. You can also include an icon by using the helper-icon prop, which utilizes the Iconify icon library.

Using Helper Text Directly to Props

Month Year Picker

/

This is a helper message

Property Value:

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    class="[&>p]:mc-m-0"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    helper-icon="ph:warning-circle-fill"
    helper-text="This is a helper message"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

import { Icon } from '@iconify/vue';

const monthYearPickerModel = ref('');
</script>

Using Helper Text Slot

Month Year Picker

/

This is a helper message

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    class="[&>p]:mc-m-0"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    display-helper
  >
    <template #helperMessage>
      <span>This is a helper message</span>
    </template>
  </mc-month-year-picker>
</template>

<script lang="ts" setup>
import { ref } from 'vue';

import { Icon } from '@iconify/vue';

const monthYearPickerModel = ref('');
</script>

Error State

To handle error states, add the error prop to the month year picker. You can also include an icon by using the helper-icon prop, which utilizes the Iconify icon library.

Using Helper Text Directly to Props

Month Year Picker

/

This is a helper message

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    helper-icon="ph:warning-circle-fill"
    helper-text="This is a helper message"
    display-helper
    error
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

import { Icon } from '@iconify/vue';

const monthYearPickerModel = ref('');
</script>

Using Helper Text Slot

Month Year Picker

/

This is a helper message

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    display-helper
    error
  >
    <template #helperMessage>
      <Icon icon="ph:warning-circle-fill" width="20px" height="20px" />
      <span>This is a helper message</span>
    </template>
  </mc-month-year-picker>
</template>

<script lang="ts" setup>
import { ref } from 'vue';

import { Icon } from '@iconify/vue';

const monthYearPickerModel = ref('');
</script>

Manually Set Current Year

You can manually set the current year to be shown in the picker. The default current year is the current year. Pass the current-year prop to set the current year.

Month Year Picker

/

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    current-year="2000"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

import { Icon } from '@iconify/vue';

const monthYearPickerModel = ref('');
</script>

Manually Set Min-Max Year

It also allows you to manually set the minimum and maximum year to be shown in the picker. The default minimum year is set 1900 and the maximum year is the current year.

Month Year Picker

/

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    :min-max-year="minMaxYear"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');

const minMaxYear = ref({
  min: 2000,
  max: 2025,
});
</script>

Pre-selected Month-Year

You can pre-select a month-year by just adding value in your v-model. The value should be in the format MM-YYYY or your specified format.

Month Year Picker

/

<template>
  <mc-month-year-picker id="monthyearpicker" v-model="monthYearPickerModel" label="Month Year Picker" display-helper />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('09-1997');
</script>

Get Date Formats

To get the date formats, you can use the @get-date-formats emits. When the month-year is valid it will return different formats.

Output:

{}

Month Year Picker

/

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    @get-date-formats="getMonthYearDateFormats"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');

const getMonthYearDateFormats = (date) => {
  console.log(date);
};
</script>

Get Month Lists

To get the month lists used, you can use the @get-month-list emits.

Month Year Picker

/

Output:

[]

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    @get-month-list="getMonthYearMonthList"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');

const getMonthYearMonthList = (date) => {
  console.log(date);
};
</script>

Get Year Lists

To get the year lists used, you can use the @get-year-list emits.

Month Year Picker

/

Output:

[]

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    @get-year-list="getMonthYearYearList"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');

const getMonthYearYearList = (date) => {
  console.log(date);
};
</script>

Error Handling

Since there is existing error handling for the month year picker, you can use the @get-date-errors emit to get the list of component-level error validations.

List of component-level error validations:

• Validate month-year if it is valid MM/YYYY
• Validate year if it is under min and max year

Output:

[]

Month Year Picker

/

<template>
  <mc-month-year-picker
    id="monthyearpicker"
    v-model="monthYearPickerModel"
    label="Month Year Picker"
    @get-date-errors="getMonthYearDateErrors"
    display-helper
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const monthYearPickerModel = ref('');

const getMonthYearDateErrors = (errors) => {
  console.log(errors);
};
</script>

Popper Strategy

The Popper strategy is primarily used when working with elements like modal. It helps control the positioning behavior of popper. The strategy ensures that the popper element is dynamically positioned based on the viewport, the reference element, or other factors such as scrolling or resizing.

By default, the Popper strategy is set to absolute, which positions the popper element relative to the nearest positioned ancestor (usually the body element). However, you can change the strategy to fixed, which positions the popper element relative to the viewport, ensuring that it remains in place even when the page is scrolled.

Pass the prop popper-strategy to change the behavior position of the popper.

Important to note:

Do not forget to pass prop wrapperPosition to overwrite relative position into initial.

<template>
  <mc-button tone="success" @click="modalModel = true">Open Modal</mc-button>

  <mc-modal v-model="modalModel" title="Month Year Picker with Modal">
    <mc-month-year-picker
      id="monthyearpicker"
      v-model="monthYearPickerModel"
      label="Month Year Picker"
      popper-strategy="fixed"
      wrapper-position="initial"
      display-helper
    />
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore
      magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
      Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    </p>
  </mc-modal>
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const modalModel = ref(false);

const monthYearPickerModel = ref('');
</script>

You can also use the popper-container prop to specify a custom container for the popper element. This is useful when you want to restrict the popper's positioning context to a specific element within your application.

Since the popper is being teleported to a different container, the popper-width prop will not work as expected. To set a custom width for the popper in this case, you can use custom styles or CSS classes to define the desired width.

<template>
  <div>
    <mc-dropdown
      id="sample-dropdownCustomPopperMonthYear"
      width="300px"
      :triggers="['hover', 'click']"
      :popper-triggers="['hover', 'click']"
      popper-width="500px"
      :auto-hide="false"
    >
      <mc-button class="mc-w-full" tone="success" has-icon>
        <span>Custom Popper With Dropdown</span>
        <Icon icon="ph:caret-down" />
      </mc-button>
      <template #popper>
        <mc-month-year-picker
          id="monthyearpicker"
          v-model="monthYearPickerModel"
          label="Month Year Picker"
          popper-strategy="fixed"
          popper-container="#sample-dropdownCustomPopperMonthYear"
          wrapper-position="initial"
          display-helper
        />
      </template>
    </mc-dropdown>
  </div>
</template>

Action

Month Year Picker

/

<template>
  <div class="mc-space-y-2">
    <mc-button tone="success" @click="clearMonthYear()">Clear Month Year</mc-button>
    <mc-month-year-picker
      ref="monthYearPickerRef"
      id="monthyearpicker"
      v-model="monthYearPickerModel"
      label="Month Year Picker"
    />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue';
import { Icon } from '@iconify/vue';

const monthYearPickerModel = ref('');
const monthYearPickerRef = ref(null);

const clearMonthYear = () => {
  monthYearPickerRef.value.clear();
};
</script>

API Reference

Props

Property	Description	Type	Default
id	Required to bind popper within the month year picker	String	-
v-model	Binds the selected month-year value	String	-
label	Label text for the input field	String	-
width	Sets the width of the input	String	100%
format	Format for the selected month-year (e.g., 'MM-YYYY', 'YYYY-MM', 'MMMM YYYY')	String	MM-YYYY
disabled	Disables the month year picker	Boolean	false
readonly	Makes the month year picker read-only	Boolean	false
helper-text	Displays a helper message below the input	String	-
helper-icon	Icon to display alongside the helper message	String	-
display-helper	Shows the helper message	Boolean	false
error	Indicates that there is an error with the input	Boolean	false
current-year	Sets the current year in the picker view	String	2026
min-max-year	Sets the minimum and maximum years in the picker	Object	{ min: 1900, max: 2026 }
placement	Changes the placement of the dropdown popper (e.g., `bottom`, `top`, `left`, `right`)	string	`bottom`
wrapper-position	CSS position of the month year picker wrapper	String	relative
popper-strategy	Popper positioning strategy ('absolute' or 'fixed')	String	absolute
popper-container	CSS selector or HTMLElement to specify a custom container for the popper element	String | HTMLElement	''

Events

Event	Description	Parameters
@update:model-value	Emits when the selected month-year value changes	String (formatted month-year)
@get-input-value	Emits the actual month-year that is being typed or selected on the picker	String | null
@get-date-formats	Emits the available date formats when a valid month-year is selected	Object (various month-year format strings)
@get-month-list	Emits the list of months available in the component	Array (month objects)
@get-year-list	Emits the list of years available in the component	Array (year numbers)
@get-date-errors	Emits validation errors from the month year picker	Array (error objects with title and message)