Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Month Picker

Examples

The Month Picker component renders a grid of checkboxes with shortened month names as well as buttons for selecting or deselecting all. For internationalization one can pass a locale prop, and the month names will change to match the language of the locale. Full month names are also included as aria-label attributes.

Loading

Code

React

React Properties Documentation
NameTypeDefaultDescription
namerequiredstringThe input field's name attribute
classNamestringAdditional classes to be added to the root element.
buttonVariationButtonVariationVariation string to be applied to buttons. See Button component
disabledMonthsnumber[]Array of month numbers, where 1 is January, and any month included is disabled for selection.
selectedMonthsnumber[]Array of month numbers, where 1 is January, and any month included is selected. This will render a read-only field. If the field should be mutable, use defaultSelectedMonths.
defaultSelectedMonthsnumber[]Array of month numbers, where 1 is January, and any month included is selected by default. Sets the initial checked state for the 12 month checkboxes. Use this for an uncontrolled component; otherwise, use the selectedMonths property.
onChange(event: ChangeEvent<HTMLInputElement>) => anyA callback function that's invoked when a month's checked state is changed. Note: This callback is not called when a month is selected or deselected via the "Select all" or "Clear all" buttons – use the onSelectAll and onClearAll event handlers for those instances.
onSelectAll() => any
onClearAll() => any
selectAllTextstringThe text for the "Select all" button for internationalization
clearAllTextstringThe text for the "Clear all" button for internationalization
errorPlacement"top" | "bottom"Location of the error message relative to the field input
idstringA unique id for the field element. Useful for referencing the field from other components with aria-describedby.
labelrequiredReactNodeLabel for the field.
labelClassNamestringAdditional classes to be added to the field label
labelIdstringA unique id to be used on the field label. If one isn't provided, a unique ID will be generated.
errorMessageReactNodeEnable the error state by providing an error message.
errorMessageClassNamestringAdditional classes to be added to the error message
errorIdstringThe ID of the error message applied to this field.
hintReactNodeAdditional hint text to display
inversedbooleanSet to true to apply the "inverse" theme
requirementLabelReactNodeText showing the requirement (ie. "Optional", or "Required"). In most cases, this should be used to indicate which fields are optional. See the form guidelines for more info.
textClassNamestringAdditional classes to be added to the label text.

Styles

The following CSS variables can be overridden to customize MonthPicker fields:

CSS variables for choice
VariableDefault Core Theme Value
--choice__background-colorhex value: #ffffff--color-white
--choice__background-color--checkedhex value: #0071bc--color-primary
--choice__background-color--disabledhex value: #d9d9d9--color-border
--choice__background-color--inversehex value: #ffffff00--color-transparent
--choice__background-color--disabled--inverse#e9ecf126
--choice__border-colorhex value: #262626--color-base
--choice__border-color--checkedhex value: #0071bc--color-primary
--choice__border-color--disabledhex value: #a6a6a6--color-gray-light
--choice__border-color--errorhex value: #262626--color-base
--choice__border-color--error--inversehex value: #ffffff--color-white
--choice__border-color--inversehex value: #ffffff--color-white
--choice__border-color--lefthex value: #0071bc--color-primary
--choice__border-color--focushex value: #004f84--color-primary-darker
--choice__border-color--disabled--inversehex value: #a6a6a6--color-gray-light
--choice__border-radius0px
--choice__border-width2px
--choice__color--uncheckedhex value: #ffffff--color-white
--choice__color--disabledhex value: #5a5a5a--color-gray-dark
--choice__size32px
--choice__size--small20px
--choice__size-radio22px
--choice__size-radio--small12px
--choice-label__color--disabledhex value: #5a5a5a--color-gray-dark
--choice-label__color--disabled--inversehex value: #e9ecf1--color-muted-inverse

Form components

This component also makes use of form field styles, which can be customized by the following variables:

CSS variables for form
VariableDefault Core Theme Value
--form-label__color--inversehex value: #ffffff--color-white
--form__max-width460px
--form__max-width--small6em
--form__max-width--medium12em
--form-hint__colorhex value: #5a5a5a--color-gray-dark
--form-hint__color--inversehex value: #e9ecf1--color-muted-inverse
--form-error__colorhex value: #e31c3d--color-error
--form-error__color--inversehex value: #f7bbc5--color-error-lighter

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete