> For the complete documentation index, see [llms.txt](https://gromet.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gromet.gitbook.io/docs/basics/inputs.md).

# Inputs

Inputs in Gromet define the parameters your users will see in the **Form** tab, and how they’re passed to your Python script.

Each input is declared in the YAML under a single `inputs` key (see [Quickstart](https://gromet.gitbook.io/docs/basics/pages/CyH2xJQs9yWJ1S8BYNav#id-1.-create-a-config-.yaml)). Gromet then auto-generates a form and wires the responses into your `main()` function.

### General Input Format

Each input in the YAML supports the following common keys:

* `arg`: The argument name passed to your Python `main()` function. **Must match your function parameter name exactly.**
* `title`: The label shown in the form UI.
* `type`: The input type (e.g., `file`, `text`, `dropdown`, `multiselect`, `textarea`, `date`).
* `required`: Boolean (`true` or `false`) indicating if the input is mandatory. Default is `false`.
* `placeholder`: Optional placeholder text shown inside text or textarea inputs.
* `extensions`: For file inputs, a list of allowed file extensions (e.g., `[xlsx, xls]`).
* `options`: For dropdowns and multiselects, a list of selectable options, each with `value` and `label`.

**Notes:**

* Inputs are passed to `main()` **in the order they appear** in the YAML list.
* Optional inputs not provided will be passed as `None`.

Below are the supported input types:

***

#### 📂 `file`

**YAML:**

```yaml
- arg: input_file
  title: Upload Excel File
  type: file
  required: true
  extensions: [xlsx, xls]
```

**Python:**

```python
def main(input_file):
    df = pd.read_excel(input_file)
```

> ▫️ The input is passed as a **local file path string** to your Python function.
>
> ▫️ To enable all file extensions pass an empty array as the value i.e `extensions: []`

***

#### 🔤 `text`

**YAML:**

```yaml
- arg: label
  title: Enter a Label
  type: text
  placeholder: "Report 2024"
  required: true
```

**Python:**

```python
def main(label):
    print(f"Running with label: {label}")
```

> ▫️ The value is passed as a **string**.

***

#### 📝 `textarea`

**YAML:**

```yaml
- arg: notes
  title: Add Notes
  type: textarea
  placeholder: "Optional context here"
```

**Python:**

```python
def main(notes):
    if notes:
        print("User added notes:", notes)
```

> ▫️ Multi-line text, passed as a **string**.

***

#### 🕽️ `dropdown`  -  Select a single input from a range of options

**YAML:**

```yaml
- arg: environment
  title: Choose Environment
  type: dropdown
  required: true
  options:
    - value: dev
      label: Development
    - value: prod
      label: Production
```

**Python:**

```python
def main(environment):
    if environment == "prod":
        deploy()
```

> ▫️ Passed as a **string** matching the selected `value`.

***

#### 🧑‍🤝‍🧑 `multiselect`  -  Select multiple inputs from a range of options

**YAML:**

```yaml
- arg: assignee
  title: Assign User
  type: multiselect
  options:
    - value: "u123"
      label: "Alice Lee"
    - value: "u456"
      label: "Bob Zhang"
```

**Python:**

```python
def main(assignee):
    # assignee is a list of selected 'value' strings, e.g. ["u123", "u456"]
    for user_id in assignee:
        print(f"Assigned to user id: {user_id}")
```

> ▫️ Passed as a **list of strings** (the `value`s of the selected options).

***

#### 🗓️ `date`

**YAML:**

```yaml
- arg: schedule_date
  title: Execution Date
  type: date
  required: true
```

**Python:**

```python
def main(schedule_date):
    print(f"Scheduled for: {schedule_date}")
```

> ▫️ Passed as a **string in YYYY-MM-DD** format.

***

**☑️ checkbox**

YAML:

```yaml
  - arg: accept_terms
    title: Accept Terms and Conditions
    type: checkbox
```

Python:

```python
def main(accept_terms: bool):
    if accept_terms:
        print("Terms accepted")
    else:
        print("Terms not accepted")
```

* **Python receives the checkbox value as a native `bool` type** — no manual string-to-boolean conversion needed.
* This seamless conversion is handled automatically by the Gromet input system.
* If the checkbox is required, the form enforces it must be checked (`True`) before submission.
* Frontend still stores the state as a string internally for simplicity.

***

#### 🧪 Notes

* All `arg` names must match the function parameters in `main()`
* Inputs are passed in **positional order** (by YAML list order)
* Optional fields will be passed as `None` if not provided