# Input
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"
}
})
```
---
# 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://docs.menanak47.com/plugins/ak47_lib/interface/input.md?ask=
```
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.