DateTime

Combined date and time picker input for selecting both date and time. Provides native datetime‑local picker on most platforms.

Use Cases

• Event start/end datetime selection (conferences, meetings, webinars)
• Appointment scheduling with specific date and time
• Deadline or due date with time specification
• Timestamp fields (created at, updated at, published at)
• Data‑bound datetime fields connected to page data sources

Properties

name

Unique field name. Type: string.

label

Label displayed above datetime picker. Type: string.

required

Whether datetime selection is required. Type: boolean. Default: false.

defaultValue

Default datetime value in YYYY‑MM‑DDTHH:MM format (ISO 8601 datetime‑local) (not used when dataBinding is set). Type: string.

width

CSS width of the datetime input container. Type: string. Default: 100%.

Tip: Recommendations – full-width: use ‘100%’ for standalone fields (default); half-width: use ‘75%’ when pairing two datetimes in a Grid; three-quarter: use ‘75%’ for prominent fields.

min

Minimum selectable datetime in YYYY‑MM‑DDTHH:MM format. Prevents selection of earlier datetimes. Type: string.

Visual Impact: Datetimes before min are disabled/grayed out in picker.

Tip: Recommendations – futureOnly: set to current datetime to block past dates; range: set to start datetime for end fields; validation: enforce business rules such as minimum 24‑hour advance booking.

max

Maximum selectable datetime in YYYY‑MM‑DDTHH:MM format. Prevents selection of later datetimes. Type: string.

Visual Impact: Datetimes after max are disabled/grayed out in picker.

Tip: Recommendations – endRange: limit unreasonable future dates; validation: enforce rules such as maximum 1‑year advance booking.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string.

Security Note: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

dataBinding

Data binding configuration to connect datetime input to page data source field. Automatically populates datetime value and saves changes back to source. Type: object.

pageDataSourceRef

Reference to page‑level data source (format: ‘@page.{dataSourceId}’). Takes precedence over sourceId/sourceType. Type: string.

sourceId

ID of the data source (database table or API connection). Type: string. Required.

sourceType

Type of data source. Type: string. Required. Options: table, api.

operationType

Operation type – ‘Get’ for single record (input fields use Get). Type: string. Required. Options: Get.

fieldName

Name of the field/column to bind to (should be datetime or timestamp field). Type: string. Required.

isReadOnly

Whether datetime input is read‑only (display only, no write back). Type: boolean. Default: false.

writeOperation

Write operation type when saving changes. Type: string. Options: Create, Update. Default: Update.

Best Practices

• Use DateTime when both date AND time are important (appointments, events, deadlines).
• Use separate Date + Time components when users might pick date first, then time later.
• Set clear labels: ‘Event Start’, ‘Appointment DateTime’, ‘Deadline’ (not just ‘DateTime’).
• Set required: true for mandatory datetimes.
• Use min/max to restrict datetime selection to valid ranges.
• Use dataBinding for edit forms to auto‑populate datetimes from data source.

Common Mistakes

Using DateTime when separate Date and Time would be better

Why it's a problem: DateTime pickers can be clunky on mobile – sometimes users prefer picking date first, then time separately.

Fix: Consider using separate Date + Time components if workflow is sequential (pick date, then pick time).

Stacking DateTime fields at full width without grouping related datetimes

Why it's a problem: Wastes horizontal space – related datetimes (Event Start + Event End) should be side‑by‑side.

Fix: Group related DateTime fields in Grid with numColumns: 2 (Event Start + Event End).

Using vague labels like ‘DateTime’ or ‘DateTime 1’

Why it's a problem: Unclear what datetime is being requested – confuses users.

Fix: Be specific: ‘Event Start’, ‘Event End’, ‘Appointment Date & Time’, ‘Deadline’.

Not setting required: true for mandatory datetimes

Why it's a problem: No visual indicator that datetime is required – users skip it and get validation errors.

Fix: Set required: true for mandatory datetimes (shows an asterisk indicator).