Available from v1.7.0
DateInput
The design system includes two date picker components: TextFieldDateInput and CompactDateInput, both offering themed date selection with formatted display and error handling.
Platform availability: iOS 17.0+
It includes the following features:
- Native UIDatePicker integration.
- Formatted date display in text field.
- Error state with customizable error label.
- Multiple style states (normal, focused, error, disabled).
- Configurable date formatting and placeholder text.
- Support for leading and trailing icons.
When to use:
- Use TextFieldDateInput when you need a date picker integrated with a text field that shows the formatted date, ideal for forms.
- Use CompactDateInput when space is limited and you prefer the native iOS compact date picker style.
- Consider using TextInput with custom validation when you need users to type dates manually in a specific format.
Import
import BackbaseDesignSystem
Visual reference
|
Error |
Disabled |
DateInput Focus |
CompactDateInput Focus |
|
API reference
TextFieldDateInput
A UIView component that displays a text field with date picker for date selection.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
border |
DesignSystem.BorderOptions? |
The border options. Default is nil |
|
cornerRadius |
DesignSystem.CornerRadiusTypes |
The corner radius of the text field. Default is .none |
|
currentDate |
Date? |
The selected date (read-only) |
|
datePicker |
UIDatePicker |
The date picker shown when text field is focused |
|
disabledStyle |
Style<TextFieldDateInput>? |
The style for disabled state |
|
displayValueFormatter |
((Date) -> String)? |
The formatter for displaying the date |
|
displayValuePlaceholder |
String? |
The placeholder text when no date is selected |
|
errorLabel |
UILabel |
The error label shown when error is set |
|
errorStyle |
Style<TextFieldDateInput>? |
The style for error state |
|
focusedStyle |
Style<TextFieldDateInput>? |
The style for focused state |
|
leftIcon |
UIImage? |
The left icon image. Default is nil |
|
leftViewOffset |
CGVector |
The left view offset. Default is .zero |
|
normalStyle |
Style<TextFieldDateInput>? |
The style for normal state |
|
normalTextColor |
UIColor? |
The color of text when a date is selected |
|
restingTextColor |
UIColor? |
The color of placeholder when no date is selected |
|
rightIcon |
UIImage? |
The right icon image. Default is nil |
|
rightViewOffset |
CGVector |
The right view offset. Default is .zero |
|
textField |
UITextField |
The text field to display the selected date |
|
textFieldPaddings |
UIEdgeInsets |
The edge insets of the text field. Default is .zero |
Initializers
init(frame:)
Creates a date input with default style and .date picker mode.
|
Parameter |
Type |
Description |
|---|---|---|
|
frame |
CGRect |
The frame rectangle. Default is .zero |
init(frame:datePickerMode:style:)
|
Parameter |
Type |
Description |
|---|---|---|
|
frame |
CGRect |
The frame rectangle. Default is .zero |
|
datePickerMode |
UIDatePicker.Mode |
The date picker mode |
|
style |
Style<TextFieldDateInput> |
The style. Default is DesignSystem.shared.styles.defaultTextFieldDateInput |
Methods
setDate(_:animated:)
Sets a date to the date picker.
|
Parameter |
Type |
Description |
|---|---|---|
|
date |
Date |
The date to set |
|
animated |
Bool |
Whether to animate the change |
removeDate(animated:)
Removes the current date selection.
|
Parameter |
Type |
Description |
|---|---|---|
|
animated |
Bool |
Whether to animate the change |
setLocale(_:)
Sets the locale of the date picker.
|
Parameter |
Type |
Description |
|---|---|---|
|
locale |
Locale |
The locale to set |
onValueChanged(_:)
Adds a callback for value changes.
|
Parameter |
Type |
Description |
|---|---|---|
|
handler |
(Date?) -> Void |
The callback to execute when value changes |
onTraitCollectionChanged(_:)
Adds a callback for trait collection changes.
|
Parameter |
Type |
Description |
|---|---|---|
|
handler |
(UITraitCollection?) -> Void |
The callback to execute when traits change |
setError(message:)
Shows an error message on the error label.
|
Parameter |
Type |
Description |
|---|---|---|
|
message |
String |
The error message to display |
clearError()
Clears the error message.
CompactDateInput
A UIView component using .compact date picker style.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
datePicker |
UIDatePicker |
The compact style date picker |
|
disabledStyle |
Style<CompactDateInput>? |
The style for disabled state |
|
errorLabel |
UILabel |
The error label shown when error is set |
|
errorStyle |
Style<CompactDateInput>? |
The style for error state |
|
normalStyle |
Style<CompactDateInput>? |
The style for normal state |
|
spacing |
CGFloat |
The spacing between date picker and error label |
Initializers
init(frame:)
Creates a compact date input with default style and .date picker mode.
|
Parameter |
Type |
Description |
|---|---|---|
|
frame |
CGRect |
The frame rectangle. Default is .zero |
init(frame:datePickerMode:style:)
|
Parameter |
Type |
Description |
|---|---|---|
|
frame |
CGRect |
The frame rectangle. Default is .zero |
|
datePickerMode |
UIDatePicker.Mode |
The date picker mode |
|
style |
Style<CompactDateInput> |
The style. Default is DesignSystem.shared.styles.defaultCompactDateInput |
Methods
setError(message:)
Shows an error message.
|
Parameter |
Type |
Description |
|---|---|---|
|
message |
String |
The error message to display |
- clearError(): Clears the error message.
- setDate(_:animated:): Sets a date to the date picker.
|
Parameter |
Type |
Description |
|---|---|---|
|
date |
Date |
The date to set |
|
animated |
Bool |
Whether to animate the change |
setLocale(_:)
Sets the locale of the date picker.
|
Parameter |
Type |
Description |
|---|---|---|
|
locale |
Locale |
The locale to set |
onValueChanged(_:)
Adds a callback for value changes.
|
Parameter |
Type |
Description |
|---|---|---|
|
handler |
(Date) -> Void |
The callback to execute when value changes |
onTraitCollectionChanged(_:)
Adds a callback for trait collection changes.
|
Parameter |
Type |
Description |
|---|---|---|
|
handler |
(UITraitCollection?) -> Void |
The callback to execute when traits change |
Configuration
TextFieldDateInput global properties
|
Property |
Description |
|---|---|
|
design.colors.surfacePrimary.default |
Background color for normal state |
|
design.colors.surfacePrimary.onSurfacePrimary.default |
Text color for normal state |
|
design.colors.inputBorder |
Border color for normal state |
|
design.colors.primary.default |
Border color for focused state |
|
design.colors.danger.default |
Border and text color for error state |
|
design.colors.surfaceDisabled.onSurfaceDisabled.disabled |
Border and text color for disabled state |
|
design.colors.surfaceDisabled.default |
Background color for disabled state |
|
design.sizer.sm |
Top and bottom padding |
|
design.sizer.md |
Leading and trailing padding |
|
design.spacer.xs |
Spacing between error label and text field |
CompactDateInput global properties
|
Property |
Description |
|---|---|
|
design.colors.primary.default |
Date picker label color in normal state |
|
design.colors.danger.default |
Error label text color and date picker label color in error state |
|
design.colors.surfaceDisabled.onSurfaceDisabled.default |
Date picker label color in disabled state |
|
design.colors.surfaceDisabled.default |
Background color for disabled state |
|
design.colors.neutrals.neutral20 |
Background color in light mode for normal/error state |
|
design.colors.neutrals.neutral80 |
Background color in dark mode for normal/error state |
Usage
Basic TextFieldDateInput
let dateInput = TextFieldDateInput()
dateInput.displayValuePlaceholder = "Select a date"
dateInput.displayValueFormatter = { date in
let formatter = DateFormatter()
formatter.dateStyle = .medium
return formatter.string(from: date)
}
With date picker mode
let dateTimeInput = TextFieldDateInput(
datePickerMode: .dateAndTime,
style: DesignSystem.shared.styles.defaultTextFieldDateInput
)
Handling date changes
let dateInput = TextFieldDateInput()
dateInput.onValueChanged { date in
if let date = date {
print("Selected date: \(date)")
} else {
print("Date cleared")
}
}
Setting a date programmatically
let dateInput = TextFieldDateInput()
dateInput.setDate(Date(), animated: true)
With error message
let dateInput = TextFieldDateInput()
dateInput.setError(message: "Please select a valid date")
// Clear error
dateInput.clearError()
CompactDateInput basic usage
let compactDateInput = CompactDateInput()
compactDateInput.onValueChanged { date in
print("Selected: \(date)")
}
CompactDateInput with date and time
let compactDateInput = CompactDateInput(
datePickerMode: .dateAndTime,
style: DesignSystem.shared.styles.defaultCompactDateInput
)
States and variants
Normal state
The default appearance when the date picker is not focused and has no errors.
let dateInput = TextFieldDateInput()
dateInput.displayValuePlaceholder = "Select a date"
Focused state
The appearance when the date picker text field is focused. The focusedStyle is applied automatically for TextFieldDateInput.
Error state
The appearance when validation fails or an error message is set.
dateInput.setError(message: "Please select a valid date")
Disabled state
The appearance when the date picker is disabled and not interactive.
dateInput.isUserInteractionEnabled = false
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.defaultTextFieldDateInput |
Default style for TextFieldDateInput |
|
DesignSystem.shared.styles.defaultCompactDateInput |
Default style for CompactDateInput |
Error handling
Set and clear errors manually:
let dateInput = TextFieldDateInput()
// Show error
dateInput.setError(message: "Please select a valid date")
// Clear error
dateInput.clearError()
Events
|
Event |
Type |
Description |
|---|---|---|
|
onValueChanged |
(Date?) -> Void |
Called when the selected date changes (TextFieldDateInput) |
|
onValueChanged |
(Date) -> Void |
Called when the selected date changes (CompactDateInput) |
|
onTraitCollectionChanged |
(UITraitCollection?) -> Void |
Called when the trait collection change |
let dateInput = TextFieldDateInput()
dateInput.onValueChanged { date in
if let date = date {
print("Selected date: \(date)")
}
}
dateInput.onTraitCollectionChanged { traitCollection in
print("Trait collection changed")
}
Accessibility
Both date input components are built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityIdentifier |
Sets identifiers for the text field, error label, and date picker subviews |
String |
Best practices
- Both components use UIDatePicker which has built-in accessibility support.
- Set meaningful accessibilityIdentifier values for testing and debugging.
- Ensure error messages are descriptive and announced via VoiceOver.
Dependencies
- External dependencies: None
- Internal dependencies:
- TextField: Internal text field component
- DesignSystem.CornerRadiusTypes: Corner radius configuration
- DesignSystem.BorderOptions: Border configuration
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Token groups used by DatePicker:
DatePicker uses the same tokens as the TextInput component:
- color/text-input/default: Default state colors
- color/text-input/focused: Focused state colors
- color/text-input/error: Error state colors
- color/text-input/disabled: Disabled state colors
State tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Default |
theme.color.text-input.default.[background|foreground|border] |
See TextInput |
|
Focused |
theme.color.text-input.focused.[background|foreground|border] |
See TextInput |
|
Error |
theme.color.text-input.error.[background|foreground|border] |
See TextInput |
|
Disabled |
theme.color.text-input.disabled.[background|foreground|border] |
See TextInput |
Semantic tokens
These tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.surfacePrimary.default |
Background color |
|
Colors |
Theme.colors.primary.default |
Focused border color |
|
Colors |
Theme.colors.danger.default |
Error state color |
|
Spacing |
DesignSystem.shared.spacer.md |
Medium spacing |
|
Spacing |
DesignSystem.shared.spacer.xs |
Spacing between error label and text field |
|
Sizer |
DesignSystem.shared.sizer.sm |
Top and bottom padding |
|
Styles |
DesignSystem.shared.styles.defaultTextFieldDateInput |
Default TextFieldDateInput style |
|
Styles |
DesignSystem.shared.styles.defaultCompactDateInput |
Default CompactDateInput style |