Date and Time Inputs

Create date, time, and datetime input fields with validation

Overview

Forms.md provides three methods for collecting date and time information: dateInput for dates only, timeInput for times only, and datetimeInput for combined date and time values.

dateInput

Collect date values in YYYY-MM-DD format.

Method Signature

dateInput(
  name: string,
  params: FormFieldSharedParamsType & DateInputParamsType
): string

Parameters

name · string · required

The unique identifier for this input field.

question · string · required

The main question or label displayed to the user.

placeholder · string

Placeholder text for the input.

placeholder: "Select a date"

min · string

Minimum allowed date value in YYYY-MM-DD format.

min: "2024-01-01"

max · string

Maximum allowed date value in YYYY-MM-DD format.

max: "2024-12-31"

step · string

Sets the stepping interval (in days).

step: "7"  // Weekly intervals

value · string

Pre-selected date value in YYYY-MM-DD format.

value: "2024-06-15"

Examples

Basic Date

composer.dateInput("birthday", {
  question: "What is your date of birth?",
  required: true,
  max: "2006-12-31",
  description: "You must be 18 or older"
});

timeInput

Collect time values in HH:mm 24-hour format.

Method Signature

timeInput(
  name: string,
  params: FormFieldSharedParamsType & TimeInputParamsType
): string

Parameters

name · string · required

The unique identifier for this input field.

question · string · required

The main question or label displayed to the user.

placeholder · string

Placeholder text for the input.

min · string

Minimum allowed time value in HH:mm format.

min: "09:00"

max · string

Maximum allowed time value in HH:mm format.

max: "17:00"

step · string

Sets the stepping interval in seconds. Common values:

• "900" - 15 minute intervals
• "1800" - 30 minute intervals
• "3600" - 1 hour intervals

step: "1800"  // 30 minute intervals

value · string

Pre-selected time value in HH:mm format.

value: "14:30"

Examples

Basic Time

composer.timeInput("meetingTime", {
  question: "What time works best for you?",
  required: true,
  step: "1800",
  description: "Times shown in 30-minute intervals"
});

datetimeInput

Collect combined date and time values in YYYY-MM-DDTHH:mm format.

Method Signature

datetimeInput(
  name: string,
  params: FormFieldSharedParamsType & DatetimeInputParamsType
): string

Parameters

name · string · required

The unique identifier for this input field.

question · string · required

The main question or label displayed to the user.

placeholder · string

Placeholder text for the input.

min · string

Minimum allowed datetime value in YYYY-MM-DDTHH:mm format.

min: "2024-01-01T09:00"

max · string

Maximum allowed datetime value in YYYY-MM-DDTHH:mm format.

max: "2024-12-31T17:00"

step · string

Sets the stepping interval in seconds.

step: "1800"  // 30 minute intervals

value · string

Pre-selected datetime value in YYYY-MM-DDTHH:mm format.

value: "2024-06-15T14:30"

Examples

Basic Datetime

composer.datetimeInput("appointment", {
  question: "When would you like to schedule your appointment?",
  required: true,
  min: "2024-01-01T09:00",
  max: "2024-12-31T17:00"
});

Use Cases

Date Only

Use dateInput when time is not relevant:

• Birthdays
• Start/end dates
• Date ranges
• Historical dates
• Deadlines (day level)

composer.dateInput("deliveryDate", {
  question: "When should we deliver?",
  min: "2024-01-01",
  required: true
});

Time Only

Use timeInput when date is not relevant or handled separately:

• Daily schedules
• Business hours
• Recurring time preferences
• Time slots

composer.timeInput("pickupTime", {
  question: "Preferred pickup time",
  min: "08:00",
  max: "20:00",
  step: "1800"
});

Date and Time

Use datetimeInput when both date and time are needed:

• Appointments
• Event registrations
• Booking systems
• Deadlines (precise time)
• Scheduling

composer.datetimeInput("bookingTime", {
  question: "Select date and time",
  required: true,
  min: "2024-01-01T00:00",
  step: "900"
});

Format Reference

All date and time inputs follow ISO 8601 format standards.

Date Format

// Format: YYYY-MM-DD
"2024-03-15"  // March 15, 2024
"2024-12-31"  // December 31, 2024
"2023-01-01"  // January 1, 2023

Best Practices

Setting appropriate ranges

Always set realistic min and max values:

// Birthdays - max prevents future dates, min prevents unrealistic ages
max: new Date().toISOString().split('T')[0],
min: "1920-01-01"

// Appointments - only allow future dates
min: new Date().toISOString().split('T')[0]

// Business hours
min: "09:00",
max: "17:00"

Using step values

Set appropriate step intervals:

• Most meetings: "900" (15 min) or "1800" (30 min)
• All-day events: Don’t set step, or use "86400" (1 day)
• Quick bookings: "300" (5 min)
• General scheduling: "3600" (1 hour)

Clear descriptions

Help users understand the format and constraints:

description: "You must be 18 or older to register"
description: "Select a date in the next 30 days"
description: "Available Monday-Friday, 9 AM to 5 PM"
description: "Times shown in your local timezone"

Timezone considerations

Be explicit about timezone handling:

description: "All times in Pacific Time (PT)"
description: "Times shown in your local timezone"

Consider collecting timezone separately for datetime inputs:

composer.datetimeInput("meetingTime", { /* ... */ });
composer.selectBox("timezone", {
  question: "Your timezone",
  options: ["PST", "EST", "CST", "MST"]
});

Return Value

Each method returns a string containing the Forms.md markup.

Submitted values:

• dateInput: "YYYY-MM-DD" (e.g., "2024-03-15")
• timeInput: "HH:mm" (e.g., "14:30")
• datetimeInput: "YYYY-MM-DDTHH:mm" (e.g., "2024-03-15T14:30")

Related Methods

textInput

General text input for custom date formats

selectBox

Dropdown for selecting months, years, or timezones