Month picker

Examples​

Check out the Usage section for details about how to design a month picker properly, and the different configuration options we provide.

Pick a month​

You can allow the user to pick a month using the MonthPicker component and then use the handler to get the selected month. Users will select a combined month and year.

import { MonthPicker } from '@jutro/components/new';

export function MonthSelector() {
  function handleMonthChange(event, value) {
    console.log('The user selected the following month:', value);
    // displays: { year: 2023, month: 1 }
  }

  return (
    <MonthPicker
      label={{
        id: 'month-picker-label',
        defaultMessage: 'Enter month',
      }}
      onChange={handleMonthChange}
    />
  );
}

Controlled month picker​

You can control the month picker by passing the value prop. This is useful if you want to use the month picker as a controlled component.

import { MonthPicker } from '@jutro/components/new';

function MonthPickerControlled() {
  const [picked, setMonth] = React.useState({ year: 2023, month: 1 });

  function handleMonthChange(event, value) {
    setMonth(value);
  }

  return (
    <MonthPicker
      label={{
        id: 'month-picker-label',
        defaultMessage: 'Enter month',
      }}
      onChange={handleMonthChange}
      value={picked}
    />
  );
}

Note that the value prop is an object with properties called year and month.

const dateObjectFromInput = new Date(picked.year, picked.month, 1, 0, 0);
const formattedTime = Intl.DateTimeFormat('en-US').format(dateObjectFromInput);

Specify interval​

You can specify the "min" and "max" date range to limit the amount of valid options, for example "January 2024" and "December 2024" would limit it to any month in 2024.

<MonthPicker
  label="Pick a month"
  minMonth={{
    year: 2024,
    month: 1,
  }}
  maxMonth={{
    year: 2024,
    month: 12,
  }}
/>

Usage​

Overview​

Month picker is a control element where the user selects a specific month from a calendar or enters it manually. This component is commonly used in insurance applications where users need to specify a month, such as selecting the start date for an insurance policy or filtering data by date.

When to use​

When the user needs to select a month.

When not to use​

• When the user needs to enter a month that's in the distant past or future. In this case, use the date input.
• When the user needs to select the month, day, and year. In this case, use the date picker.
• When the user only needs to select a year. In this case, use the year picker.

Formatting​

Anatomy​

The month picker component consists of the following elements:

1. Date picker field: An input field where the user can manually enter the month and year.
2. Calendar icon: An icon button that triggers the dropdown calendar when clicked.
3. Previous year button: A navigational control for viewing and selecting the months of the previous year.
4. Year button: A control for selecting a different year.
5. Next year button: A navigational control for viewing and selecting the months of the next year.
6. Selected month: The specific month chosen by the user and highlighted or emphasized within the month picker interface.
7. “Current month” button: A button that automatically populates the month picker field with the current month and year when clicked.

Date format​

A MM/YYYY placeholder within the input field guides users on the expected month and year format as they type.

Content​

General writing guidelines​

• Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
• Use present tense verbs and active voice in most situations.
• Use common contractions to lend your copy a more natural and informal tone.
• Use plain language. Avoid unnecessary jargon and complex language.
• Keep words and sentences short.

Include a label​

Label the month picker with clear, descriptive text. This label must communicate its purpose and the specific type of month being selected.

Do position a permanent label outside the field.

Don't use placeholder text as a replacement for the label.

Add help text if it's meaningful​

Use help text to provide context and communicate what month to select. Here are some examples of what you might include:

• Hints that assist the user in choosing the appropriate month
• More context for why the user needs to select a specific month

Only use help text for pertinent information. Avoid restating the same details that appear in the label. Write help text in sentence case, using 1-2 short, complete sentences that end with a period.

Do use help text to show context.

Don't use help text to simply restate the same information that appears in the label.

Behaviors​

States​

The month picker component behaves like an input field, with the same interactive states.

Interactions​

Mouse​

Users can enter the month and year manually in the date picker field or click the calendar icon to select the month and year from a dropdown.

Keyboard​

The date picker is expanded and collapsed with Spacebar. Users navigate through the options using the arrow keys and select by means of the Spacebar or Enter key.

A calendar widget appears when the user tabs to the date picker input field. The current date is highlighted and keyboard-only users can enter the date manually here. Users can also place keyboard focus on the widget by pressing the down arrow key when it is expanded. Navigate through the calendar with the arrow keys. 'Previous', 'Month', 'Year', and 'Next' buttons are focusable using the Tab key when the widget is open.

Screenreader​

Users are informed of the pre-populated date value when they tab to the date picker input field, and that this value is currently selected. The date can be entered manually from this input field. While focus remains on the pre-populated date, a calendar widget is also available. Users can also move focus into the widget by pressing the down arrow key. Navigation through the calendar portion of the widget is accomplished via the arrow keys, and the value currently in focus is voiced by screen readers via a WAI-ARIA aria-label attribute. The 'Previous', 'Month', 'Year', and 'Next' buttons are focusable using the Tab key when the widget is open. React date picker does not currently enable keyboard navigation to the 'Today' link.

Input handling​

The month picker component allows users to move the caret (the blinking text cursor) between different sections of the date (MM/YYYY). However, users cannot delete individual digits within a section. Deleting any digit erases the entire section (MM or YYYY), requiring users to retype it. This behavior is consistent across date components, where the input mask formats the input as the user types.

Accessibility​

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

When using this component, ensure that the label clearly communicates which month the user needs to input or select.

Code​

<MonthPicker
  label={{
    id: 'month-picker-label',
    defaultMessage: 'Enter month',
  }}
  name="Dinner month picker"
  onChange={handleMonthChange}
/>

Import statement​

import { MonthPicker } from '@jutro/components/new';

Component contract​

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties​

labelrequired​

Type

IntlMessageShape

Description

Label associated with the input field, also passed as a default value to 'aria-label'.

className​

Type

string

Description

CSS class passed to the root element of the component

disabled​

Type

bool

Description

If true, component is rendered in disabled state.

displayFormat​

Type

'vshort' | 'short' | 'long'

Description

The date format.

displayOnly​

Type

bool

Description

If true, displays the component value as a plain text. Consider using readonly instead, if possible, because plain text has much worse accessibility than readonly inputs.

hideCurrentMonthButton​

Type

bool

Description

Hide current month button in calendar.

hideLabel​

Type

bool

Description

If true, the label is not visible. Default to false.

initialValue​

Type

{ month: number, year: number }

Description

Initial value of input. Value must be in object format with month and year property where month is indexed from 1. If value prop is specified along with this prop, this prop's value is discarded.

labelPosition​

Type

'top | 'left'

Description

Allows to select label position.

maxMonth​

Type

{ month: number, year: number }

Description

Maximum allowed month value.

minMonth​

Type

{ month: number, year: number }

Description

Minimum allowed month value.

onBlur​

Type

function (FocusEvent<HTMLInputElement>)

Description

A callback called after the component is focused.

onChange​

Type

function (React.ChangeEvent<HTMLInputElement>, { month: number, year: number })

Description

Callback invoked when component value is changed.

onFocus​

Type

function (FocusEvent<HTMLInputElement>)

Description

A callback called after the component is focused.

placeholder​

Type

IntlMessageShape

Description

Placeholder to display on an empty component.

readOnly​

Type

bool

Description

If true, component is rendered in read-only state. For value as a plain text consider using displayOnly.

required​

Type

bool

Description

If true, component is rendered as required and label has asterisk.

secondaryLabel​

Type

IntlMessageShape

Description

Secondary label text to display.

stateMessages​

Type

{ error: string[] }

Description

An object with a list of error messages for the current state.

tooltip​

Type

{ text: intlMessageShape, trigger: string } | intlMessageShape

Show object details

text​

Type

IntlMessageShape

Description

Text to show tooltip content.

trigger​

Type

string

Description

The trigger to show the tooltip

Description

Text to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger

value​

Type

{ month: number, year: number }

Description

Value of input. Takes precedence over initialValue. Value must be in object format with month and year property where month is indexed from 1. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.

Hooks​

No hooks are available for MonthPicker.

Translation keys​

The MonthPicker component defines one translation key:

MonthPicker also inherits the following translations:

Date format and localization​

The date is formatted according to the selected locale. For example, if the locale is en-US, then the date January 20th, 2024 is formatted as "01/20/2024". If the locale is en-GB, it is formatted as "20/01/2024".

Escape Hatches​

For more information, see our documentation about escape hatches.

The following options are available:

• Design tokens
• A className property
• The ability to pass the supported HTML attributes
• Ref with imperative handlers
• A native event property

Ref with imperative handlers​

Jutro inputs have implemented imperative handlers as a mechanism to provide access to some common native features that might be useful for you. The following features are available:

• Set focus to allow you to set the user focus into a specific component

• Blur to remove the focus from the component

• Scroll to the component so that you can take the user to a specific area of the page.

These features are provided through the ref property, which exposes them as follows:

    const componentRef = useRef(null);

    const setFocus = () => {
        componentRef?.current.focus();
    }

    const removeFocus = () => {
        componentRef?.current.blur();
    }

    const scrollToComponent = () => {
        componentRef?.current.scrollIntoView();
    }

    <Component ref={componentRef}>

More options might be included in the future.

Precedence of disabled, displayOnly, and readOnly properties​

If two or more of the properties disabled, displayOnly, and readOnly are set to true at the same time, the precedence is as follows:

displayOnly > readOnly > disabled

User input validation​

Although some Jutro components might provide complementary features or a helper function to facilitate the validation process, it is your responsibility as a developer to handle the validation of any user input (using or not using the complementary helpers) and to decide what error messages to show.

Jutro components behave based on the developer implementation.

When are error messages displayed?

Error messages are only displayed when you pass them to the component through the stateMessages property. This property receives an object with the following content:

{
  error: ['error message 1', 'error message 2', 'error message N'];
}

The component displays every error message provided in the same order as in the array.

When does validation occur?

This is your decision as a developer. As components do not determine when the validation is performed or when the error must be displayed, you need to implement the logic to handle it according to the project requirements, for example while the user is editing the content, when the component loses focus, and on form submission.

Additional validation for MonthPicker​

If the user enters an invalid date, or a date that is outside the min/max boundaries, they get a validation error as the third parameter in the onChange handler. The parameter looks like the following:

{
  errorCode: ERROR.<ERROR_CODE_GOES_HERE>,
}

The error code can be one of the following:

• INVALID_DATE - when the user enters an invalid date, for example "January 32nd".
• MIN_DATE_EXCEEDED - when the user enters a date that is before minDate.
• MAX_DATE_EXCEEDED - when the user enters a date that is after maxDate.

Changelog​

10.5.0​

New @jutro/components/MonthPicker component introduced that replaces MonthYearField.

MonthYearField can still be imported from @jutro/components/MonthYearField, but you will get a warning that it is deprecated when doing so.