The jQuery UI Month Picker Plugin

The jQuery UI Month Picker Plugin was designed to allow users to choose only a month and year when only that input is required. Clicking on the year, allows the user to jump ahead or back 5 years at a time. Clicking anywhere on the page, except on the month picker menu itself, will cause the month picker to hide.

Demonstration & Unit Testing

Icon Demonstration
This demonstrates the default option for showing an icon.

Choose a Month:

No Icon Demonstration
This demonstrates setting options for removing the icon.

Choose a month:

Start Year Demonstration
This demonstrates how the plugin will default to the year specified in the text box. Changing the year in the text box will result in a new default year for the chooser and if no date is selected then the default year is the current year.

Choose a month:

Override Start Year Demonstration
This demonstrates how the MonthPicker can be configured to override the start year default behavior. This MonthPicker will start on 2023 no matter which date is currently selected, even if no date is specified.

Choose a month:

Get Month/Year & Validation API Demonstration
This demonstrates API usage for the GetSelectedMonthYear(), GetSelectedYear() and GetSelectedMonth() function calls which will also perform date validation. Clear() will clear the text field and any validation messages.

Choose a month:

Disable/Enable API Demonstration
This demonstrates API usage for the Enable() and Disable().

Choose a month:

Digital Bush Integration Demonstration
This demonstrates how the MonthPicker plugin integrates with the Digital Bush Plugin for Input Masking as well as the html 5 placeholder attribute to simulate watermarking. Try to type an invalid date and try the Get Month/Year button to fire off validation.

Type in a month/year:


Type in a month/year::


jQuery UI Dialog Integration Demonstration
This demonstrates the Month Picker running inside of the jQuery UI Modal Dialog.

.position() Integration Demonstration
This demonstrates the Month Picker integration with the optional .position() plugin. The right aligned input helps to show how the menu will not allow the edges of the window to hide it's appearance. The menu will position itself so that it is always visible. The same effect can be seen on every other month picker on this page by scrolling down low enough so that the menu shows above the input instead of below.


Choose a month:

Error Checking
This demonstrates what will happen if the MonthPicker is called on html elements other than a text input.

#MySpan

Unit Test Results

qUnit Testing Output

    test markup

    Documentation Reference

    Source Code Example

    This plugin can only be called on text boxes as follows.

    $('#TextBox1').MonthPicker({ StartYear: 2020, ShowIcon: false });
    $('#TextBox2').MonthPicker().css('backgroundColor', 'lightyellow');
            

    Prerequisites

    This plugin has been tested using the following configuration.

    Options

    Disabled Type: Boolean Default: false
    Disables/enables the MonthPicker on initialization.

    Code Examples

    Initialize a MonthPicker with the disabled option specified.

    $('.selector').MonthPicker({ Disabled: true });

    Get or set the disabled option, after init.
    //getter
    var disabled = $('.selector').MonthPicker('option', 'Disabled');
    
    //setter $('.selector').MonthPicker('option', 'Disabled', true );
    ShowIcon Type: boolean Default: true
    Indicates whether or not to show an icon that opens the month picker. Without an icon, the month picker menu will show upon focus of the text box.

    Code Example

    Initialize a MonthPicker with the ShowIcon option specified.
    $('.selector').MonthPicker({ ShowIcon: true });
    

    Get or set the disabled option, after init.
    //getter
    var disabled = $('.selector').MonthPicker('option', 'ShowIcon');
    
    //setter $('.selector').MonthPicker('option', 'ShowIcon', true );
    StartYear Type: int Default: The current year.
    Sets the starting year in the month picker. This setting will over ride all other start year behaviors.

    Code Example

    Initialize a MonthPicker with the StartYear option specified.
    $('.selector').MonthPicker({StartYear:  });

    Get or set the disabled option, after init. Set to null to omit this behavior.
    //getter
    var disabled = $('.selector').MonthPicker('option', 'StartYear');
    
    //setter $('.selector').MonthPicker('option', 'StartYear', 2032);
    ValidationErrorMessage Type: Nullable string Default: null
    Specifies the validation error message and if specified will activate date validation when the text box loses focus and when any of the API methods are called.

    Code Example

    Initialize a MonthPicker with the ValidationErrorMessage option specified.
    $('.selector').MonthPicker({ValidationErrorMessage: 'Invalid Date!' });
    Get or set the ValidationErrorMessage option, after init. Set to null to omit this behavior.
    //getter
    var disabled = $('.selector').MonthPicker('option', 'ValidationErrorMessage');
    
    //setter $('.selector').MonthPicker('option', 'ValidationErrorMessage', 'Invalid Date!');
    UseInputMask Type: bool Default: false
    Directs the MonthPicker to use the Digital Bush InputMask jQuery Plugin which must be loaded to the page if this option is to be used.

    Code Example

    Initialize a MonthPicker with the UseInputMask option specified.
    $('.selector').MonthPicker({UseInputMask: true });
    Get or set the UseInputMask option, after init.
    //getter
    var disabled = $('.selector').MonthPicker('option', 'UseInputMask');
    
    //setter $('.selector').MonthPicker('option', 'UseInputMask', false);

    API Methods

    $('.selector').MonthPicker('Clear')
    If the Digital Bush Watermark plugin is activated. This will set the field to a blank value and show the watermark again.

    $('.selector').MonthPicker('ClearAllCallbacks')
    Disables all previously assigned event callbacks listed in the Events tab.

    $('.selector').MonthPicker('Disable')
    Disables the MonthPicker and its associated elements.

    $('.selector').MonthPicker('Enable')
    Enables the MonthPicker and its associated elements.

    $('.selector').MonthPicker('GetSelectedMonthYear')
    Validates the selected month/year and returns the selected value if it is a valid date. Returns null if there is no valid date, displays an error message if the message is specified, focuses and selects the violating text.

    $('.selector').MonthPicker('GetSelectedMonth')
    Returns only the month portion of the selected date as an integer. Returns NaN if there is no valid date.

    $('.selector').MonthPicker('GetSelectedYear')
    Returns only the year portion of the selected date as an integer. Returns NaN if there is no valid date.

    Events

    OnAfterMenuOpen
    This event is triggered after the MonthPicker opens.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterMenuOpen: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterMenuOpen');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterMenuOpen', function(){});
    OnAfterMenuClose
    This event is triggered after the MonthPicker menu is closed.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterMenuClose: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterMenuClose');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterMenuClose', function(){});
    OnAfterNextYear
    This event is triggered when the MonthPicker Next Year button is clicked.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterNextYear: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterNextYear');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterNextYear', function(){});
    OnAfterNextYears
    This event is triggered when the MonthPicker Jump Ahead 5 Years button is clicked.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterNextYears: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterNextYears');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterNextYears', function(){});
    OnAfterPreviousYear
    This event is triggered when the MonthPicker Previous Year button is clicked.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterPreviousYear: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterPreviousYear');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterPreviousYear', function(){});
    OnAfterPreviousYears
    This event is triggered when the MonthPicker Jump Back 5 Years button is clicked.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterPreviousYears: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterPreviousYears');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterPreviousYears', function(){});
    OnAfterChooseMonth
    This event is triggered when a month button is clicked in the picker.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterChooseMonth: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterChooseMonth');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterChooseMonth', function(){});
    OnAfterChooseMonths
    This event is triggered when the choose months button is clicked in the picker.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterChooseMonths: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterChooseMonths');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterChooseMonths', function(){});
    OnAfterChooseYear
    This event is triggered when a year button is clicked in the picker.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterChooseYear: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterChooseYear');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterChooseYear', function(){});
    OnAfterChooseYears
    This event is triggered when the choose years button is clicked in the picker.

    Code Example

    Supply a callback function to handle the event as an init option.
    $('.selector').MonthPicker({OnAfterChooseYears: function(){} });
    Get or set the callback function, after init.
    //getter
    var myFunction = $('.selector').MonthPicker('option', 'OnAfterChooseYears');
    
    //setter $('.selector').MonthPicker('option', 'OnAfterChooseYears', function(){});

    The MonthPicker plugin uses the jQuery UI CSS Framework to style its look and feel, including the colors of buttons and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.

    If a deeper level of customization is needed, there are widget-specific classes referenced within the MonthPicker.css stylesheet that can be modified. These classes are highlighed below.

    .month-picker-disabled
    Customize the disabled look of the MonthPicker text box.

    .month-picker-invalid-message
    Customize the look of validation message.

    .month-year-input
    Customize the look of the MonthPicker text input box in an enabled state.

     

    Fork me on GitHub