Skip to main content

Component | Time Input

info

Introduced in v0.22.0 of the SDK.

Render a time input box.

ui.timeInput("time-input-key", { 
    label: "What time is it right now?",
    onEnter: (value) => console.log(value)
})

Learn more about working with inputs.

API reference​

Function signature​

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

/**
 * An object with human readable values for hour (0-23) and minute (0-59)
 */
type TimeOutput = 
    | {
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | null // Passes `null` if no date was selected

ui.timeInput(
    id: string,
    properties: Partial<{
        label: string,
        description: string,
        required: boolean, // Default: true,
        min: TimeInput,
        max: TimeInput,
        initialValue: TimeInput, // Default: null
        validate: (value: TimeOutput) => string | void,
        onEnter: (value: TimeOutput) => void,
        style: Style | null
    }>
)

Parameters​

id

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

properties.label

optional string

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

properties.description

optional string

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

properties.required

optional boolean

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

properties.min Optional TimeInput​

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

The parameter expects either a JS Date in UTC or a human readable object with hour (0-23) and minute (0-59).

type TimeInput = 
    | {
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | Date // Assumes UTC for the given date
    | null // Use default value (i.e. no minimum time)

properties.max Optional TimeInput​

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

The parameter expects either a JS Date in UTC or a human readable object with hour (0-23) and minute (0-59).

type TimeInput = 
    | {
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | Date // Assumes UTC for the given date
    | null // Use default value (i.e. no maximum time)

properties.initialValue Optional TimeInput​

The initial value to set for the date input. If not provided, the date input will be empty initially.

The parameter expects either a JS Date in UTC or a human readable object with hour (0-23) and minute (0-59).

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

properties.validate Optional (value: TimeOutput) => string | void​

Supply a custom function to validate the time input.

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

type TimeOutput = 
    | {
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | null // Passes `null` if no time was selected

properties.onEnter Optional (value: TimeOutput) => void​

Supply a callback function that is called when the user presses enter while the time input is focused.

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

type TimeOutput = 
    | {
        hour: number; // 0-23
        minute: number; // 0-59
    }
    | null // Passes `null` if no time was selected

properties.style

optional Style

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