# Input

<figure><img src="https://2088945756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkHcyR2RbVMcj5NHJ2HEa%2Fuploads%2F9EMVhNcel9SesBj6yPep%2Fimage.png?alt=media&#x26;token=1c15a1b3-db78-4af2-9643-9f656bb92af7" alt=""><figcaption></figcaption></figure>

This function displays a customizable input dialog to the player. It is a wrapper that automatically switches between your custom React interface (`Interface.ShowInput`) based on your `Config.InputDialog` setting.

### Syntax

```lua
Lib47.ShowInput(heading, rows, options)
```

#### Parameters

| **Argument** | **Type** | **Description**                                                           |
| ------------ | -------- | ------------------------------------------------------------------------- |
| `heading`    | String   | The title text displayed at the top of the dialog.                        |
| `rows`       | Table    | An array of tables, where each table represents an input field.           |
| `options`    | Table    | (Optional) A table containing global configuration for the dialog window. |

#### Return Value

* Success: Returns a `table` (array) containing the input values in the order of the rows.
* Cancel: Returns `nil` if the user cancels the dialog (presses Escape or the Cancel button).

***

### Row Properties

Each entry in the `rows` table can contain the following properties.

#### Common Properties (All Types)

| **Property**  | **Type** | **Default** | **Description**                                             |
| ------------- | -------- | ----------- | ----------------------------------------------------------- |
| `type`        | String   | `'input'`   | The type of input field (see list below).                   |
| `label`       | String   | -           | The text label displayed above the input.                   |
| `description` | String   | -           | Small helper text displayed below the input.                |
| `icon`        | String   | -           | FontAwesome icon class (e.g., `'fa-user'`).                 |
| `required`    | Boolean  | `false`     | If true, the user cannot submit without filling this field. |
| `disabled`    | Boolean  | `false`     | If true, the field is visible but not editable.             |
| `default`     | Mixed    | -           | The initial value of the field.                             |
| `placeholder` | String   | -           | Placeholder text inside the input field.                    |

#### Input Types

| **Type**         | **Specific Properties**                | **Description**                 |
| ---------------- | -------------------------------------- | ------------------------------- |
| `'input'`        | `minLength`, `maxLength`, `password`   | Standard text input.            |
| `'textarea'`     | `min` (rows), `max` (rows), `autosize` | Multi-line text area.           |
| `'number'`       | `min`, `max`, `step`, `precision`      | Numeric input.                  |
| `'slider'`       | `min`, `max`, `step`                   | A visual range slider.          |
| `'select'`       | `options`, `clearable`, `searchable`   | Single-choice dropdown.         |
| `'multi-select'` | `options`, `maxSelectedValues`         | Multiple-choice dropdown/chips. |
| `'checkbox'`     | -                                      | A boolean toggle switch.        |
| `'date'`         | `format`, `returnString`               | Date picker.                    |
| `'time'`         | -                                      | Time picker.                    |
| `'date-range'`   | `format`, `returnString`               | Start and End date picker.      |
| `'color'`        | -                                      | RGB Hex color picker.           |

> Note: For `select` and `multi-select`, the `options` property must be an array of objects structured as `{ value = "val", label = "Label" }`.

***

### Dialog Options

The third argument, `options`, controls the window's appearance and behavior.

| **Option**    | **Type**    | **Default** | **Description**                                       |
| ------------- | ----------- | ----------- | ----------------------------------------------------- |
| `allowCancel` | Boolean     | `true`      | Whether the generic "Cancel" button is shown.         |
| `size`        | String      | `'md'`      | Window width: `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`. |
| `borders`     | Table/Array | -           | Add accent borders. Example: `{'left', 'right'}`.     |
| `colors`      | Table       | -           | Custom coloring for this specific dialog instance.    |

**Colors Structure**

```lua
colors = {
    colorPrimary = "rgba(15, 15, 20, 0.85)", -- Background
    colorSecondary = "#FFD700",              -- Accent/Buttons
    colorText = "#ffffff"                    -- Text Color
}
```

***

### Examples

#### 1. Basic Information Form

A simple form to get a player's name and age.

```lua
local input = Lib47.ShowInput('Personal Information', {
    {
        type = 'input',
        label = 'Full Name',
        description = 'Enter your character name',
        required = true,
        icon = 'fa-user'
    },
    {
        type = 'number',
        label = 'Age',
        default = 18,
        min = 18,
        max = 100,
        icon = 'fa-calendar-days'
    },
    {
        type = 'textarea',
        label = 'Bio',
        placeholder = 'Tell us about yourself...',
        autosize = true
    }
})

if input then
    local name = input[1]
    local age = input[2]
    local bio = input[3]
    print('Result:', name, age, bio)
end
```

#### 2. Advanced Selection & Formatting

Using dropdowns, date ranges, and sliders with specific styling.

```lua
local options = {
    { value = 'police', label = 'Police Department' },
    { value = 'ems', label = 'Medical Services' },
    { value = 'mechanic', label = 'Mechanic' }
}

local input = Lib47.ShowInput('Job Application', {
    {
        type = 'select',
        label = 'Select Department',
        options = options,
        searchable = true, -- Allows typing to filter options
        required = true
    },
    {
        type = 'multi-select',
        label = 'Availability',
        options = {
            { value = 'mon', label = 'Monday' },
            { value = 'tue', label = 'Tuesday' },
            { value = 'wed', label = 'Wednesday' }
        },
        maxSelectedValues = 2
    },
    {
        type = 'date-range',
        label = 'Vacation Period',
        format = 'DD/MM/YYYY', -- UI will return formatted string
        returnString = true
    },
    {
        type = 'slider',
        label = 'Experience Level',
        min = 1,
        max = 10,
        step = 1,
        default = 5
    }
}, {
    size = 'lg', -- Large window
    allowCancel = true
})

if input then
    -- input[1] is the selected value string (e.g., 'police')
    -- input[2] is a table/array (e.g., {'mon', 'wed'})
    -- input[3] is a table/array (e.g., {'20/10/2023', '25/10/2023'})
    -- input[4] is a number (e.g., 5)
end
```

#### 3. Custom Themed Dialog

Override the default colors for a specific menu (e.g., a dark/red illegal shop).

```lua
local input = Lib47.ShowInput('Black Market', {
    {
        type = 'input',
        label = 'Secret Code',
        password = true, -- Hides characters
        icon = 'fa-lock'
    },
    {
        type = 'color',
        label = 'Vehicle Neons',
        default = '#ff0000'
    }
}, {
    size = 'sm',
    borders = {'top', 'bottom'}, -- Only borders on top and bottom
    colors = {
        colorPrimary = "rgba(10, 0, 0, 0.95)",
        colorSecondary = "#ff3333", -- Red accent
        colorText = "#ffcccc"
    }
})
```