DateTime

A combined date and time picker input that lets users select both a calendar date and a clock time. It uses the 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. Required.

label

Label displayed above datetime picker. Type: string. Required.

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%.

Recommendations: Use “100%” for standalone datetime fields (default); use “50%” when pairing two datetimes in a Grid (Event Start + Event End); use “75%” for prominent datetime fields in forms.

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.

Recommendations: For event scheduling, set min to current datetime to prevent past dates; for end datetimes, set min to start datetime to ensure end comes after start; use min to enforce business rules (e.g., minimum booking 24 hours in advance).

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.

Recommendations: For event scheduling, set max to prevent unreasonable future dates; use max to enforce business rules (e.g., maximum booking 1 year in advance).

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.

Properties of dataBinding:

• pageDataSourceRef (string): Reference to page‑level data source (format: '@page.{dataSourceId}'). Takes precedence over sourceId/sourceType.
• sourceId (string, required): ID of the data source (database table or API connection).
• sourceType (string, required): Type of data source. Options: table, api.
• operationType (string, required): Operation type – “Get” for single record (input fields use Get). Options: Get.
• fieldName (string, required): Name of the field/column to bind to (should be datetime or timestamp field).
• isReadOnly (boolean): Whether datetime input is read‑only (display only, no write back). Default: false.
• writeOperation (string): Write operation type when saving changes. 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 asterisk indicator).