> For the complete documentation index, see [llms.txt](https://docs.forms.md/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forms.md/input-types/datetime-input.md). # Datetime input

Datetime input

Use the `datetimeInput()` function to create datetime inputs in your forms. It uses the HTML `` element which provides a built-in datetime picker. *** ## Basic usage ```javascript import { Composer } from "formsmd"; const composer = new Composer({ id: "my-form" }); composer.datetimeInput("appointment", { question: "When would you like to schedule your appointment?" }); ``` Generates the following Markdown-like syntax: ``` #! id = my-form appointment = DatetimeInput( | question = When would you like to schedule your appointment? ) ``` ### Required Add the `required` parameter to make the field mandatory: ```javascript composer.datetimeInput("appointment", { question: "When would you like to schedule your appointment?", required: true }); ``` Generates the following Markdown-like syntax: ``` appointment* = DatetimeInput( | question = When would you like to schedule your appointment? ) ``` *** ## Function overview The following is the overview of the function: ```typescript datetimeInput(name: string, params: object) ``` ### Arguments | Name | Type | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | A unique name for your form field that you'll use to identify the user's response.\* | | `params` | `object` | An object containing all the configuration parameters for your datetime input field (see the [parameters section](#parameters) below for the full list of options). | {% hint style="danger" %} \*Avoid values for the `name` argument which may be the names of HTML attributes, such as `"name"`, `"role"`, `"id"`, etc. This is because by default, the form's template string is first sanitized using [DOMPurify](https://github.com/cure53/DOMPurify), and these values may be removed to prevent DOM clobbering. {% endhint %} *** ## Parameters ### Shared parameters These parameters are common to all form fields: | Name | Type | Description | | --------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `question` (required) | `string` | The main question or label of the form field. | | `required` | `true` (`boolean`) | When set, the field becomes required. | | `description` | `string` | Any extra information that the user may need to fill out the form. Appears right below the question. | | `fieldSize` | `"sm"` | When set to `"sm"`, the font sizes of the question, description, and answer are made smaller. | | `labelStyle` | `"classic"` | When set to `"classic"`, the question and description of the form field are made smaller. | | `subfield` | `true` (`boolean`) | When set, the question and description of the form field are made smaller. Functionally the same as setting `labelStyle` to `"classic"`. | | `disabled` | `true` (`boolean`) | When set, the input is disabled. | | `autofocus` | `true` (`boolean`) | When set, the input will be automatically focused when the parent slide becomes active, or immediately after page load. | | `id` | `string` | The `id` attribute of the form field container. | | `classNames` | `string[]` | The CSS class names of the form field. [See the available CSS utility classes](/content/css-utility-classes.md). | | `attrs` | `Array<{ name: string, value: string }>` | Other HTML attributes of the form field. Each attribute has a `name` and `value` property. | | `displayCondition` | `{ dependencies: string[], condition: string }` | Controls when the field is shown. The `dependencies` lists the fields to watch, and `condition` is the expression that must be true to show the field. The `condition` must be a valid [Nunjucks](https://mozilla.github.io/nunjucks/) expression. [See example](#conditional-display). | ### Datetime input specific parameters | Name | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------ | | `placeholder` | `string` | Sets the `placeholder` attribute of the input. | | `min` | `string` | Sets the minimum allowed datetime value. Must be in the format `"YYYY-MM-DDTHH:mm"`. | | `max` | `string` | Sets the maximum allowed datetime value. Must be in the format `"YYYY-MM-DDTHH:mm"`. | | `step` | `string` | Sets the stepping interval. | | `value` | `string` | If set, this becomes the default value of the input. Must be in the format `"YYYY-MM-DDTHH:mm"`. | *** ## Examples ### Datetime input with min and max values ```javascript composer.datetimeInput("meetingTime", { question: "When would you like to schedule the meeting?", description: "Please choose a time between 9 AM and 5 PM next week", min: "2024-01-15T09:00", max: "2024-01-19T17:00", required: true }); ``` Generates the following Markdown-like syntax: ``` meetingTime* = DatetimeInput( | question = When would you like to schedule the meeting? | description = Please choose a time between 9 AM and 5 PM next week | min = 2024-01-15T09:00 | max = 2024-01-19T17:00 ) ``` ### Datetime input with custom step interval ```javascript composer.datetimeInput("appointmentTime", { question: "Select your preferred appointment time", description: "Appointments are available in 30-minute slots", step: "1800", required: true }); ``` Generates the following Markdown-like syntax: ``` appointmentTime* = DatetimeInput( | question = Select your preferred appointment time | description = Appointments are available in 30-minute slots | step = 1800 ) ``` ### Styled datetime input with custom attributes Add CSS classes and other HTML attributes using the `classNames` and `attrs` parameters. Please note, these class names and attributes are added to the `
` or `
` container that contains the actual input field(s). ```javascript composer.datetimeInput("eventDateTime", { question: "Event date and time", classNames: ["col-6", "xs:col-6"], attrs: [ { name: "style", value: "font-size: 18px;" } ] }); ``` Generates the following Markdown-like syntax: ``` [.col-6 .xs:col-6 style="font-size: 18px;"] eventDateTime = DatetimeInput( | question = Event date and time ) ``` Please [see the available CSS utility classes](/content/css-utility-classes.md). ### Conditional display Conditionally show or hide a datetime input field using the `displayCondition` parameter. It works as follows: * `dependencies` lists the fields to watch. * `condition` is the expression that must be true to show the field. This must be a valid [Nunjucks](https://mozilla.github.io/nunjucks/) expression. For instance, in the example below, the return flight datetime input will only show up if the user selects a round trip. ```javascript composer.choiceInput("tripType", { question: "What type of trip would you like to book?", required: true, choices: ["One way", "Round trip"] }) composer.datetimeInput("returnFlight", { question: "Return flight date and time", displayCondition: { dependencies: ["tripType"], condition: "tripType == 'Round trip'" } }); ``` Generates the following Markdown-like syntax: ``` tripType* = ChoiceInput( | question = What type of trip would you like to book? | choices = One way, Round trip ) ::: [{$ tripType $}] {% if tripType == "Round trip" %} returnFlight = DatetimeInput( | question = Return flight date and time ) {% endif %} ::: ``` ## Notes * During form submission, the user's local timezone will get added to the end of the datetime input value, for example: `2024-06-01T08:30+06:00`.