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