# 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


---

# 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://gromet.gitbook.io/docs/basics/inputs.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.