Date Input

Anatomy

1. Label: Title of the input.
2. Input Container: Rectangular container that houses the date.
3. Placeholder/Input Text: Placeholder text displays the expected date formatting. As the user enters data this placeholder text is replaced with the input text.
4. Calendar Icon: Used to help aid in visually describing the context of the input.

Usage Guidance

When to Use

• When entering dates that are common to the user, like birthdays via the onscreen keyboard.
• When entering dates that are farther out, beyond a few years.

When to Consider Something Else

• Use a Text Input when the intended user input is all or partially text based.
• Consider a Prompt, Radio or Checkbox if there are relative (ie. tomorrow, 2 days after) or predetermined dates that a user can pick from.
• Use a Time Picker for all time based data (ie, 10:30 pm)
• Use a Date Picker when selecting a date within a year, past or future.
• Use a Date Picker when there may be a user benefit from understanding the day of the week.

Behaviors

Size

Date inputs are purposefully sized differently from other text inputs. Typically inputs stretch to fill the width of the screen on mobile. However dates are typically shorter in length therefore the date inputs are smaller to provide better context of the expected entry to the user. The width of the input varies based on the precision level.

Keyboard

Interaction with this input invokes a native number pad to provide easier entry of a numerical date.

Examples

The date input allows variations of date precision depending on the use case.

Day-Month-Year

Used when the full day, month and year are required. Typically in a mm/dd/yyyy format (or dd/mm/yyyy based on your location).

Month-Year

Used when only the month and year are required. Displayed in a mm/yyyy format.

Year

Used when only the year is required. Displayed in a yyyy format.

Picker

The picker style entry allows quick and easy selection of dates within a year of the current date, past or future. However, pickers may be troublesome when selecting far out dates. Consider using the keyboard style entry in these cases.

API Guidelines

Methods

Class name: LabelledDateInput Module name: UIComponentsPlugin

    public init(
        featureData: FeatureMetricsData,
        dateInput: Binding<Date?>,
        label: String,
        helperText: String?,
        dateTemplate: DateTemplate,
        context: Binding<SemanticContext>,
        isCalendarIconHidden: Bool,
        localizer: LocalizationAdapting
    )

Parameters

Accessibility Guidelines

Coming soon…

Content Guidelines

• Labels for Date Inputs are written in title case.
• Use helper text to instruct the user what the proper input may be.
• Use placeholder text only to provide examples of proper inputs. Never use placeholder text to help instruct users.

Anatomy

1. Label: Title of the input.
2. Input Container: Rectangular container that houses the date.
3. Placeholder/Input Text: Placeholder text displays the expected date formatting. As the user enters data this placeholder text is replaced with the input text.
4. Calendar Icon: Used to help aid in visually describing the context of the input.

Usage Guidance

When to Use

• When entering dates that are common to the user, like birthdays via the onscreen keyboard.
• When entering dates that are farther out, beyond a few years.

When to Consider Something Else

• Use a Text Input when the intended user input is all or partially text based.
• Consider a Prompt, Radio or Checkbox if there are relative (ie. tomorrow, 2 days after) or predetermined dates that a user can pick from.
• Use a Time Picker for all time based data (ie, 10:30 pm)
• Use a Date Picker when selecting a date within a year, past or future.
• Use a Date Picker when there may be a user benefit from understanding the day of the week.

Behaviors

Size

Date inputs are purposefully sized differently from other text inputs. Typically inputs stretch to fill the width of the screen on mobile. However dates are typically shorter in length therefore the date inputs are smaller to provide better context of the expected entry to the user. The width of the input varies based on the precision level.

Keyboard

Interaction with this input invokes a native number pad to provide easier entry of a numerical date.

Examples

The date input allows variations of date precision depending on the use case.

Day-Month-Year

Used when the full day, month and year are required. Typically in a mm/dd/yyyy format (or dd/mm/yyyy based on your location).

Month-Year

Used when only the month and year are required. Displayed in a mm/yyyy format.

Year

Used when only the year is required. Displayed in a yyyy format.

Picker

The picker style entry allows quick and easy selection of dates within a year of the current date, past or future. However, pickers may be troublesome when selecting far out dates, consider using the keyboard style entry in these cases.

Keyboard

The keyboard style entry invokes the native number pad to provide a clearer expectation for the type of entry required. This type of entry should be used for very well known dates, like birthdays, or dates well over a year out, past or future.

API Guidelines

Methods

  fun DateInputUiComponent(
    modifier: Modifier = Modifier,
    label: String,
    helperText: String? = null,
    value: LocalDate? = null,
    dateInputConfig: DateInputConfig = DateInputConfig.Full,
    setDateValue: (LocalDate?) -> Unit,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    semanticState: SemanticState = SemanticState()
)

Parameters

Accessibility Guidelines

Coming soon…

Content Guidelines

• Labels for Date Inputs are written in title case.
• Use helper text to instruct the user what the proper input may be.
• Use placeholder text only to provide examples of proper inputs. Never use placeholder text to help instruct users.