Monthpicker Field

Overview

When to use

• When asking the user to select a month, where the specific day isn’t meaningful to the task, for instance when viewing a billing period or usage period
• When it's useful for the user to be able to browse nearby months for context, or to see available months
• When months could span far into the past or future, and scrolling through individual days would be inefficient

When not to use

• When the user needs to provide an exact date - use Datepicker Field instead
• When choosing from a small, fixed set of months, for instance only the last three billing periods - use Select Field or Radio instead. Browsing a calendar adds interaction cost when there’s nothing to browse

Anatomy

1. Monthpicker field: Based on Text Field. Contains label, hint text, input and error state.
2. Calendar button: Pressing the calendar opens the calendar popover.
3. Year controls: Moves the year forwards and backwards.
4. Selected month
5. Today's month
6. This month button: Selects today's month and closes the calendar popover.
7. Clear button: Clears the current entry and closes the calendar popover.
8. Calendar popover: The menu where the month is selected. The calendar popover is always a fixed width, and always aligned to the left edge of the monthpicker field.

Basic usage

Edit live code
<MonthpickerField
  id="month"
  label="Month"
/>
<MonthpickerField
  id="month"
  label="Month"
/>

Month format and validation

MonthpickerField uses the mm/yyyy format for months and will use this format when selecting a month from the popover. The popover will attempt to parse the input value in order to show which month is selected.

The input itself is a TextInput that the user can freely enter text into and you should always validate user input when the form is submitted.

Nebula exports the function getMonthpickerDate which can be used to validate the string entered by the user in the MonthpickerField text input and that returns either a Date if valid or null if not.

Edit live code
() => {

  const Example = () => {
    const [errors, setErrors] = useState([]);

    const onSubmit = (e) => {
      e.preventDefault();
      const newErrors = [];

      const { monthpicker } = Object.fromEntries(new FormData(e.currentTarget));

      const monthpickerDate = getMonthpickerDate(monthpicker)

      if (!monthpickerDate) {
        newErrors.push({ id: 'monthpicker', message: 'Enter a valid month in the format mm/yyyy'});
      }

      setErrors(newErrors);

      if (!newErrors.length) {
        alert('success');
      }
    }

    return (
      <Form errors={errors} onSubmit={onSubmit}>
        <FormFields>
          <MonthpickerField
            id="monthpicker"
            name="monthpicker"
            label="Monthpicker example"
          />
        </FormFields>
        <FormActions>
          <PrimaryCTAButton type="submit">Submit</PrimaryCTAButton>
        </FormActions>
      </Form>
    );
  }

  return <Example />;
}
() => {

  const Example = () => {
    const [errors, setErrors] = useState([]);

    const onSubmit = (e) => {
      e.preventDefault();
      const newErrors = [];

      const { monthpicker } = Object.fromEntries(new FormData(e.currentTarget));

      const monthpickerDate = getMonthpickerDate(monthpicker)

      if (!monthpickerDate) {
        newErrors.push({ id: 'monthpicker', message: 'Enter a valid month in the format mm/yyyy'});
      }

      setErrors(newErrors);

      if (!newErrors.length) {
        alert('success');
      }
    }

    return (
      <Form errors={errors} onSubmit={onSubmit}>
        <FormFields>
          <MonthpickerField
            id="monthpicker"
            name="monthpicker"
            label="Monthpicker example"
          />
        </FormFields>
        <FormActions>
          <PrimaryCTAButton type="submit">Submit</PrimaryCTAButton>
        </FormActions>
      </Form>
    );
  }

  return <Example />;
}

Content

Writing labels

The Monthpicker Field label should always be a noun that describes the month. It should be no more than two or three words.

Don't try to make the label and month function as a sentence, such as 'Billing for {month input}'. This is harder for users to follow, and harder to communicate errors, for instance 'Enter a valid billing for' does not make sense as an error message.

Don't:

• Billing for
• Month meter reading submitted
• The month you want to install
• Renewing on

Do:

• Billing month
• Statement month
• Installation month
• Renewal month

Writing hints

Hint text may be used to help the user understand additional validation constraints on the month. The Monthpicker Field has placeholder text that specifies the format of a valid month, so it is not necessary to include the format as a hint.

Keep any extra guidance short, and avoid trying to write full sentences. Where possible, hint text should describe a valid month, not an invalid month.

Don't:

• Month
  Months before this year unavailable
• Renewal month
  Please pick a month no more than 12 months from today

Do:

• Month
  This year only
• Renewal month
  Within the next 12 months

Variations

Validation Error

Edit live code
<MonthpickerField
  id="month"
  label="Month"
  error="Enter a valid month"
/>
<MonthpickerField
  id="month"
  label="Month"
  error="Enter a valid month"
/>

Input size

Monthpicker input size is determined by a combination of the fullWidth and characters properties. By default, monthpicker inputs are an appropriate width for the expected input and stretch to full width below the smallest breakpoint.

Generally it is recommended to use the default behaviour, but in some cases you may want to set the width of the input to a specific size.

The responsive full width behaviour can be overridden by setting fullWidth="always" and fullWidth="never".

Edit live code
<MonthpickerField
  id="month"
  label="Month"
  fullWidth="always"
/>
<MonthpickerField
  id="month"
  label="Month"
  fullWidth="always"
/>

The default width itself can be overridden using the characters property, which approximates how many characters should fit into the input.

Edit live code
<MonthpickerField
  id="month"
  label="Month"
  characters={20}
/>
<MonthpickerField
  id="month"
  label="Month"
  characters={20}
/>

Unavailable months

It is possible to mark certain months as unavailable in the popover. Provide a callback to the isMonthUnavailable property to test if a given month should be unavailable.

Note that this will not prevent the user from manually entering these months so it is important to validate the input when the form is submitted.

Edit live code
<MonthpickerField
  id="month"
  label="Month"
  hint="Must be a future month"
  isMonthUnavailable={date => date.getTime() < Date.now()}
/>
<MonthpickerField
  id="month"
  label="Month"
  hint="Must be a future month"
  isMonthUnavailable={date => date.getTime() < Date.now()}
/>

Month ranges

The Monthpicker Field doesn't yet support selecting month ranges in a single field. Until it does, use two Monthpicker Fields side-by-side.

To create a relationship between the two fields, use the isMonthUnavailable property. Set months before the start month as unavailable in the end month field. Reset the end month when the start month is changed to avoid the user getting stuck.

Align side-by-side Monthpicker Fields to the bottom of the container, so that when fields have different heights (for instance when one field has hint text or an error message) the inputs remain aligned.

Edit live code
() => { // ignore - for live code example only.
  const Example = () => {
    const [startMonth, setStartMonth] = useState('');
    const [endMonth, setEndMonth] = useState('');

    const isMonthUnavailable = (date) => {
      if (!startMonth) {
        return false;
      }
      const [m, y] = startMonth.split('/');
      const start = new Date(y + '/' + m + '/01');
      return date.getTime() < start.getTime();
    };

    return (
      <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'flex-end' }}>
        <MonthpickerField
          id="start-month"
          name="start-month"
          label="Start month"
          hint="After this month"
          value={startMonth}
          onChange={value => {
            setStartMonth(value);
            setEndMonth('');
          }}
        />
        <MonthpickerField
          id="end-month"
          name="end-month"
          label="End month"
          value={endMonth}
          onChange={setEndMonth}
          isMonthUnavailable={isMonthUnavailable}
        />
      </div>
    );
  }

  return <Example />;
};
() => { // ignore - for live code example only.
  const Example = () => {
    const [startMonth, setStartMonth] = useState('');
    const [endMonth, setEndMonth] = useState('');

    const isMonthUnavailable = (date) => {
      if (!startMonth) {
        return false;
      }
      const [m, y] = startMonth.split('/');
      const start = new Date(y + '/' + m + '/01');
      return date.getTime() < start.getTime();
    };

    return (
      <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'flex-end' }}>
        <MonthpickerField
          id="start-month"
          name="start-month"
          label="Start month"
          hint="After this month"
          value={startMonth}
          onChange={value => {
            setStartMonth(value);
            setEndMonth('');
          }}
        />
        <MonthpickerField
          id="end-month"
          name="end-month"
          label="End month"
          value={endMonth}
          onChange={setEndMonth}
          isMonthUnavailable={isMonthUnavailable}
        />
      </div>
    );
  }

  return <Example />;
};

Avoid additional, overarching labels for month ranges. Instead, make the label for the start and end fields clear.

Don't:

Edit live code
<>
  <P><Strong>Billing Range</Strong></P>
  <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'flex-end' }}>
    <MonthpickerField
      id="start-month"
      name="start-month"
      label="Start"
    />
    <MonthpickerField
      id="end-month"
      name="end-month"
      label="End"
    />
  </div>
</>
<>
  <P><Strong>Billing Range</Strong></P>
  <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'flex-end' }}>
    <MonthpickerField
      id="start-month"
      name="start-month"
      label="Start"
    />
    <MonthpickerField
      id="end-month"
      name="end-month"
      label="End"
    />
  </div>
</>

Do:

Edit live code
<>
  <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'flex-end' }}>
    <MonthpickerField
      id="start-month"
      name="start-month"
      label="Billing start month"
    />
    <MonthpickerField
      id="end-month"
      name="end-month"
      label="Billing end month"
    />
  </div>
</>
<>
  <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'flex-end' }}>
    <MonthpickerField
      id="start-month"
      name="start-month"
      label="Billing start month"
    />
    <MonthpickerField
      id="end-month"
      name="end-month"
      label="Billing end month"
    />
  </div>
</>

Uncontrolled vs Controlled

It is recommended to use uncontrolled form inputs where possible (opens in new window) . When using an uncontrolled MonthpickerField you can pass a defaultValue.

Edit live code
<MonthpickerField
  id="month"
  label="Month"
  defaultValue="01/2024"
/>
<MonthpickerField
  id="month"
  label="Month"
  defaultValue="01/2024"
/>

Alternatively, you can control the input by passing value and onChange.

Edit live code
() => { // ignore - for live code example only.
  const Example = () => {
    const [month, setMonth] = useState('01/2024');

    return (
      <MonthpickerField
        id="month"
        label="Month"
        value={month}
        onChange={setMonth}
      />
    );
  }

  return <Example />;
};
() => { // ignore - for live code example only.
  const Example = () => {
    const [month, setMonth] = useState('01/2024');

    return (
      <MonthpickerField
        id="month"
        label="Month"
        value={month}
        onChange={setMonth}
      />
    );
  }

  return <Example />;
};

OverlayProvider

This component is built using the React Aria (opens in new window) . The OverlayProvider context provider is required to hide the content outside of the calendar popover from screen readers.

import { OverlayProvider } from '@react-aria/overlays';

const MyApp = () => <OverlayProvider>Welcome to my app!</OverlayProvider>
import { OverlayProvider } from '@react-aria/overlays';

const MyApp = () => <OverlayProvider>Welcome to my app!</OverlayProvider>

Properties

Related

• Form Guidelines
• Datepicker Field
• Text Fields