Date Input
Date Inputs allow users to enter or select a date.
Anatomy
- Label: Title of the input.
- Input Container: Rectangular container that houses the date.
- Placeholder/Input Text: Placeholder text displays the expected date formatting. As the user enters data this placeholder text is replaced with the input text. Only displayed when using the keyboard style entry.
- Pill: Displays the selected date. Only displayed when using the picker style entry
- Calendar Icon: Used to help aid in visually describing the context of the input.
Usage Guidance
When to Use
- When asking for a known date from the user.
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 (i.e. tomorrow, 2 days after) or predetermined dates that a user can pick from.
- Time Inputs/pickers should be used for all time based data (i.e. 10:30 pm)
Behaviors
Size
Date inputs are purposefully sized differently from other text inputs. Most of the time inputs will stretch to fill the width of the screen on mobile. Dates are typically shorter in length. The smaller date input helps provide more context into the expected entry.
Examples
The date input uses two types of data entry depending on the type of date needed.
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
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
| Name | Description |
|---|---|
| featureData | the feature name/context and the screen ID in which the component appears. |
| dateInput | Binding for the date to be displayed in the component. |
| label | title of the date input, already localized. |
| helperText | the helper text for the date input, already localized. |
| dateTemplate | Date template that defines the type fields dateinput contains ex: MMddyyyy, This displays all three fields month, day and year where as MMyyyy diplays only month and year |
| context | binding to the semantic context. |
| isCalendarIconHidden | whether the calendar icon should be shown. |
| localizer | provider of localized strings, conforming to LocalizationAdapting |
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
- Label: Title of the input.
- Input Container: Rectangular container that houses the date.
- Placeholder/Input Text: Placeholder text displays the expected date formatting. As the user enters data this placeholder text is replaced with the input text. Only displayed when using the keyboard style entry.
- Pill: Displays the selected date. Only displayed when using the picker style entry
- Calendar Icon: Used to help aid in visually describing the context of the input.
Usage Guidance
When to Use
- When asking for a known date from the user.
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 (i.e. tomorrow, 2 days after) or predetermined dates that a user can pick from.
- Time Inputs/pickers should be used for all time based data (i.e., 10:30 pm)
Behaviors
Size
Date inputs are purposefully sized differently from other text inputs. Most of the time inputs will stretch to fill the width of the screen on mobile. Dates are typically shorter in length. The smaller date input helps provide more context into the expected entry.
Examples
The date input uses two types of data entry depending on the type of date needed.
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
| Name | Description | Default values |
|---|---|---|
| label | String to display in the label above the date input. | |
| helperText | String to be displayed below the date input. | null |
| value | LocalDate object representing the current date value. | null |
| dateInputConfig | Enum for date input config, options are Full, MonthYear, and Year. | Full |
| setDateValue | Callback lambda to be executed when a valid date value is entered. When the date is incomplete or invalid, will change the date to null. | |
| interactionSource | The [MutableInteractionSource] representing the stream of Interactions for this [DateInputUiComponent]. You can create and pass in your own remembered [MutableInteractionSource] if you want to observe Interactions and customize the appearance / behavior of this [DateInputUiComponent] in different Interactions. | remember { MutableInteractionSource() } |
| semanticState | Semantic state of the date config, i.e. Warning, Error, Enabled, and Required states. | SemanticState() |
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.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #canvas or #canvas-kitchannels on Slack.
FAQ Section