# datetime-input

## Overview

`datetime-input` allows users to input a [`datetime`](https://docs.journeyapps.com/reference/data-model-configuration/model/field#date-and-time-datetime) value using a calendar and time picker.

{% hint style="info" %}
**Version compatibility**

* `datetime-input` is supported in all versions of the JourneyApps Container and Runtime.
* It received several functional updates in version **4.87.0** of the JourneyApps Runtime, most notably the addition of advanced [styling and configuration](https://docs.journeyapps.com/reference/build/app-styling-and-customizations/component-styling-and-configuration) capabilities.
  {% endhint %}

### Basic Example

{% code title="main.view\.xml" %}

```xml
<var name="my_datetime" type="datetime" />

<datetime-input label="Please specify a date and time:" bind="my_datetime" required="false" />
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FvyqNc23tIrevnKMae9QM%2Fdatetime-example.png?alt=media\&token=93cb6a49-39db-4a17-aeca-ede9a0460aae)

## Standard Attributes

### `bind`

{% content-ref url="../xml-fields/bind" %}
[bind](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/bind)
{% endcontent-ref %}

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `required`

{% content-ref url="../xml-fields/required" %}
[required](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/required)
{% endcontent-ref %}

## Advanced Attributes <a href="#standard-attributes" id="standard-attributes"></a>

### `align-content` <a href="#standard-attributes" id="standard-attributes"></a>

{% hint style="info" %}
**Version compatibility**

`align-content` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `align-label`

{% hint style="info" %}
**Version compatibility**

`align-label` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `clear-button-visibility`

{% content-ref url="../xml-fields/clear-button-visibility" %}
[clear-button-visibility](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/clear-button-visibility)
{% endcontent-ref %}

### `clear-icon`

{% hint style="info" %}
**Version compatibility**

`clear-icon` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `string`

**Default**: "fa-times"

Specify the icon on the right side of the input that appears when a date or time was selected. Find a list of available icons [here](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/icons).

### `date-placeholder`

**Optional**

**Type:** `string` (static text, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or the return value of a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml))

**Default**: "Select date"

Override the default placeholder text for the date input field.

**Note**: once the user entered a date the placeholder is no longer visible.

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FOh84LgWFuIRFsOrqJe5F%2Fdatetime-placeholder.png?alt=media&#x26;token=0ad208f8-f6ae-495e-8be2-80ce16e1f538" alt=""><figcaption></figcaption></figure>

### `disabled`

{% content-ref url="../xml-fields/disabled" %}
[disabled](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/disabled)
{% endcontent-ref %}

### `error-message`

{% hint style="info" %}
**Version compatibility**

`error-message` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/error-message" %}
[error-message](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/error-message)
{% endcontent-ref %}

### `icon-position`

{% hint style="info" %}
**Version compatibility**

`icon-position` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/icon-position" %}
[icon-position](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/icon-position)
{% endcontent-ref %}

### `id`

{% hint style="info" %}
**Version compatibility**

`id` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `modifier-text`

{% content-ref url="../xml-fields/modifier-text" %}
[modifier-text](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/modifier-text)
{% endcontent-ref %}

### `on-change`

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

### `placeholder-date`

{% hint style="danger" %}
**Deprecated**

`placeholder-date` is deprecated since version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

Deprecated. See [`date-placeholder`](#date-placeholder).

### `placeholder-time`

{% hint style="danger" %}
**Deprecated**

`placeholder-time` is deprecated since version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

Deprecated. See [`time-placeholder`](#time-placeholder).

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

### `time-format`

**Optional**

**Type:** `12h` | `24h`

**Default**: `12h`

Specify the clock format when users enter a time. Example:

* `12h` format: **3:32 PM**
* `24h` format: **15:32**

### `time-icon`

{% hint style="info" %}
**Version compatibility**

`time-icon` was introduced in version **4.87.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `string`

**Default**: "fa-clock"

Specify the icon on the right side of the time input that appears before a time was selected. Find a list of available icons [here](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/icons).

### `time-placeholder`

**Optional**

**Type:** `string` (static text, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or the return value of a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml))

**Default**: "Select time"

Override the default placeholder text for the date input field.

**Note**: once the user entered a time the placeholder is no longer visible.

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FOh84LgWFuIRFsOrqJe5F%2Fdatetime-placeholder.png?alt=media&#x26;token=0ad208f8-f6ae-495e-8be2-80ce16e1f538" alt=""><figcaption></figcaption></figure>

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.datetimeInput({id:'my-id'})` is called from JS/TS:

### `clear`

Programmatically clear the selected date and time bound to the `datetime-input` component.

### `pickDate`

Programmatically open the date picker to allow the user to select or update a date value.

### `scrollIntoView`

Programmatically scroll until the `datetime-input` is visible in the view.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/datetime-input.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.