Component | DateTime Input

info

Introduced in v0.22.0 of the SDK.

Render a datetime input box.

Node.js

ui.dateTimeInput("date-input-key", { 
    label: "When will the world end?",
    onEnter: (value) => console.log(value)
})

Python

ui.datetime_input(
    "date-input-key",
    label="When will the world end?",
    on_enter=lambda value: print(value)
)

Learn more about working with inputs.

API reference

Function signature

Node.js

/**
 * One of the following:
 * - A JS Date object in UTC
 * - A human readable object with year, month (1-12), day (1-31), hour (0-23), and minute (0-59)
 * - `null` to ignore the parameter and use the default value
 */
type DateTimeInput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | Date // Assumes UTC for the given date
    | null

/**
 * One of the following:
 * - An object with human readable values for year, month (1-12), day (1-31), hour (0-23), minute (0-59),
 *   and a JS Date object with the selected datetime in UTC
 * - `null` if no datetime was selected
 */
type DateTimeOutput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
        jsDate: Date; // Selected datetime in UTC
    }
    | null // Passes `null` if no datetime was selected

ui.dateTimeInput(
    id: string,
    properties: Partial<{
        label: string,
        description: string,
        required: boolean,
        min: DateTimeInput,
        max: DateTimeInput,
        initialValue: DateTimeInput,
        validate: (value: DateTimeOutput) => string | void,
        onEnter: (value: DateTimeOutput) => void,
        style: Style | null
    }>
)

Python

ui.datetime_input(
    id: str,
    *,
    label: str | None = None,
    description: str | None = None,
    required: bool = True,
    min: datetime.datetime | None = None,
    max: datetime.datetime | None = None,
    initial_value: datetime.datetime | None = None,
    validate: Callable[[datetime.datetime | None], str | None] | None = None,
    on_enter: Callable[[datetime.datetime | None], None] | None = None,
    style: Style | None = None
)

Parameters

Node.js

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Python

id

required str

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

---

Node.js

properties.label

optional string

The label to display above the datetime input. If not provided, the label will be inferred from the id.

Python

label

optional str

The label to display above the datetime input. If not provided, the label will be inferred from the id.

---

Node.js

properties.description

optional string

A description to display between the label and datetime input box.

Python

description

optional str

A description to display between the label and datetime input box.

---

Node.js

properties.required

optional boolean

Validate that the datetime input is not empty before submitting the form it's part of or calling it's onEnter hook. Defaults to true.

Python

required

optional bool

Validate that the datetime input is not empty before submitting the form it's part of or calling it's on_enter hook. Defaults to True.

---

Node.js

properties.min optional DateTimeInput

Python

min optional datetime.datetime | None

The earliest datetime that can be selected. If not provided, there is no minimum datetime.

Node.js

The parameter expects either a JS Date in UTC or a human readable object with year, month (1-12), day (1-31), hour (0-23), and minute (0-59).

type DateTimeInput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | Date // Assumes UTC for the given date
    | null // Use default value (i.e. no minimum datetime)

Python

The parameter expects either a datetime.datetime object or None to ignore the parameter and use the default value.

DateTimeType = datetime.datetime | None

---

Node.js

properties.max optional DateTimeInput

Python

max optional datetime.datetime | None

The latest datetime that can be selected. If not provided, there is no maximum datetime.

Node.js

The parameter expects either a JS Date in UTC or a human readable object with year, month (1-12), day (1-31), hour (0-23), and minute (0-59).

type DateTimeInput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | Date // Assumes UTC for the given date
    | null // Use default value (i.e. no maximum datetime)

Python

The parameter expects either a datetime.datetime object or None to ignore the parameter and use the default value.

DateTimeType = datetime.datetime | None

---

Node.js

properties.initialValue optional DateTimeInput

Python

initial_value optional datetime.datetime | None

The initial value of the datetime input. Defaults to null. You can also update the value of the datetime input at any time using the page.setInputs() method.

Node.js

The parameter expects either a JS Date in UTC or a human readable object with year, month (1-12), day (1-31), hour (0-23), and minute (0-59).

type DateTimeInput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | Date // Assumes UTC for the given date
    | null // Use default value (i.e. no initial value)

Python

The parameter expects either a datetime.datetime object or None to ignore the parameter and use the default value.

DateTimeType = datetime.datetime | None

---

Node.js

properties.validate optional (value: DateTimeOutput) => string | void

Python

validate optional Callable[[datetime.datetime | None], str | None]

Validate the input value before submitting it. If the function returns a string, it will be displayed as an error message.

Node.js

The validator will be passed an object with the following properties:

type DateTimeOutput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
        jsDate: Date; // Selected datetime in UTC
    }
    | null // Passes `null` if no datetime was selected

Python

The validator will be passed a datetime.datetime variable with the selected datetime or None if no datetime was selected.

DateTimeType = datetime.datetime | None

---

Node.js

properties.onEnter optional (value: DateTimeOutput) => void

Python

on_enter optional Callable[[datetime.datetime | None], None]

A callback function that is called when the user presses enter in the datetime input.

Node.js

The callback will be passed an object with the following properties:

type DateTimeOutput = 
    | {
        year: number;
        month: number; // 1-12
        day: number; // 1-31
        hour: number; // 0-23
        minute: number; // 0-59
        jsDate: Date; // Selected datetime in UTC
    }
    | null // Passes `null` if no datetime was selected

Python

The callback will be passed a datetime.datetime variable with the selected datetime or None if no datetime was selected.

DateTimeType = datetime.datetime | None

---

Node.js

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

---