## input


Your scripting extension can ask the user for input using the built-in `input` object. Each interactive input method is [asynchronous](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous), which means you should prefix each call with `await`.


Your scripting automation action can use inputs that are passed to it using the built-in `input` object.
Click '+ Add property' within 'Script input' and specify the keys and values of your input.
Keys must be string literals, while values may use template expressions which allow you to refer to
the results of previous automation steps.


### textAsync (extensions only)

```js
async function (label: string) => Promise<string>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining what the user should enter. |

Prompts the user to enter text. It's similar to `prompt()` in normal JavaScript, but looks much nicer.

```js
let name = await input.textAsync('What is your name?');
output.text(`Your name is ${name}.`);
```

### buttonsAsync (extensions only)

```js
async function (
    label: string,
    options: Array<string | {
        label: string,
        value?: any,
        variant?: 'default' | 'danger' | 'primary' | 'secondary'
    }>
) => Promise<string>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining what the user is choosing. |
| `options` | An array of options for the user to choose from. |

Prompts the user to choose one from a list of several options.

You can mix and match both string and object options. The function will return either the label string, or the value from the object if one is specified.

```js
let catOrDog = await input.buttonsAsync('Cats or dogs?', ['Cats!', 'Dogs!']);
if (catOrDog === 'Cats!') {
    output.text('Meow');
} else {
    output.text('Woof');
}
```

```js
let shouldContinue = await input.buttonsAsync(
    'Should we delete all the records in your base?',
    [
        {label: 'Cancel', value: 'cancel'},
        {label: 'Go for it', value: 'yes', variant: 'danger'},
    ],
);

if (shouldContinue === 'yes') {
    output.text('I refuse!');
}
```

```js
let today = new Date();
let tomorrow = new Date();
tomorrow.setDate(today.getDate() + 1);
let date = await input.buttonsAsync(
    'When should this event start?',
    [
        {label: 'Today', value: today},
        {label: 'Tomorrow', value: tomorrow},
    ],
);
output.text(date.toDateString());
```

### tableAsync (extensions only)

> See also: [Table](/developers/scripting/api/table.md)
```js
async function (label: string) => Promise<Table>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining which table the user should pick. |

Prompts the user to choose a table from a list of all tables in the base.

```js
// prompt the user to pick a table, then show the number of records in that table:
let table = await input.tableAsync('Pick a table');
let result = await table.selectRecordsAsync({fields: []});
output.text(`There are ${result.records.length} records in '${table.name}'.`);
```

### viewAsync (extensions only)
> See also: [Table](/developers/scripting/api/table.md)
> See also: [View](/developers/scripting/api/view.md)
```js
async function (label: string, table: Table) => Promise<View>;
async function (label: string, tableName: string) => Promise<View>;
async function (label: string, tableId: string) => Promise<View>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining which view the user should pick. |
| `tableOrTableNameOrTableId` | Either a [Table](/developers/scripting/api/table.md) instance or the name/id of a table in your base |

Prompts the user to choose a view belonging to the table specified by `tableOrTableNameOrTableId`.

```js
// prompt the user to pick a view in "Projects", then show the number of records in that view:
let view = await input.viewAsync("Pick a view", "Projects");
let result = await view.selectRecordsAsync({fields: []});
output.text(`There are ${result.records.length} records in '${view.name}'.`);
```

### fieldAsync (extensions only)
> See also: [Table](/developers/scripting/api/table.md)
> See also: [Field](/developers/scripting/api/field.md)
```js
async function (label: string, table: Table) => Promise<Field>;
async function (label: string, tableName: string) => Promise<Field>;
async function (label: string, tableId: string) => Promise<Field>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining which field the user should pick. |
| `tableOrTableNameOrTableId` | Either a [Table](/developers/scripting/api/table.md) instance or the name/id of a table in your base |

Prompts the user to choose a field belonging to the table specified by `tableOrTableNameOrTableId`.

```js
let field = await input.fieldAsync("Pick a field", "People");
output.text(`You picked the '${field.name}' field.'`);
```

### recordAsync (extensions only)
> See also: [Table](/developers/scripting/api/table.md)
> See also: [View](/developers/scripting/api/view.md)
> See also: [Record](/developers/scripting/api/record.md)
> See also: [RecordQueryResult](/developers/scripting/api/recordqueryresult.md)
> See also: [Field](/developers/scripting/api/field.md)
```js
async function (
    label: string,
    source: Table | View | Array<Record> | RecordQueryResult,
    options: {
        fields?: Array<Field | string>;
        shouldAllowCreatingRecord?: boolean;
    },
) => Promise<Record | null>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining what the picked record will be used for. |
| `source` | The source for the records to pick from. To allow picking any record in a [table](/developers/scripting/api/table.md), a [view](/developers/scripting/api/view.md) or a [record query result](/developers/scripting/api/recordqueryresult.md), pass it here directly. To limit picking from a specific list of [records](/developers/scripting/api/record.md), pass the list instead. |
| `options` | **Optional.** Options for the record picker. |
| `options.fields` | **Optional.** The [fields](/developers/scripting/api/field.md) or field names/ids to include in the record cards and the returned record. The primary field will always be shown. Duplicate fields will be removed. |
| `options.shouldAllowCreatingRecord` | **Optional.** If set to true, the user will be able to create an empty new record from the record picker. |

Expands a list of records in the Airtable UI, and prompts the user to pick one.

If the user picks a record, the [record](/developers/scripting/api/record.md) instance is returned. If the user dismisses the picker, `null` is returned. If there are no records to pick from in the `source`, the picker is not shown and `null` is returned.


#### Button field (extensions only)
To use your script with the "Run script" action of a button field, use `recordAsync` with the
`Table` that contains the button field, or a `View` from that table.

When the script is run from a button, the first `recordAsync` call in your script will use the
button's record instead of prompting the user. The record must be from the same `Table`, or if
using a `View`, be visible within that view.

If the record satisfies those criteria, the prompt will be skipped and the button's record will be returned.
Otherwise, a warning will be shown and the user will be prompted to pick a record.

You can use the [Record picker example](/developers/scripting/examples/recordpicker.md) as a starting point for a button field script.


```js
/* Pick from a table */
let table = base.getTable("Tasks");
let record = await input.recordAsync('Pick a record', table);
if (record) {
    output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
```

```js
/* Pick from a view */
let table = base.getTable("Tasks");
let view = table.getView("Backlog");
let record = await input.recordAsync('Pick a record', view);
if (record) {
    output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
```

```js
/* Pick from a record query result */
let table = base.getTable("Tasks");
let result = await table.selectRecordsAsync({sorts: [{field: "Priority"}]});
let record = await input.recordAsync('Pick a record', result);
if (record) {
    output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
```

```js
/* Pick from a list of records */
let table = base.getTable("Tasks");
let result = await table.selectRecordsAsync({fields: ["Description"]});
let records = result.records.filter((_, i) => i % 2 == 0);  // Filter out every other record
let record = await input.recordAsync('Pick a record', records);
if (record) {
    output.text(`You picked ${record.getCellValueAsString("Description")}`);
}
```

```js
/* Options */
let table = base.getTable("Tasks");
let record = await input.recordAsync('Pick a record', table, {
    fields: ["Priority"],
    shouldAllowCreatingRecord: true,
});
if (record) {
    output.text(`You picked ${record.getCellValueAsString("Priority")}`);
}
```

### fileAsync (extensions only)
```js
async function (
    label: string,
    options?: {
        hasHeaderRow?: boolean,
        allowedFileTypes?: Array<string>
        useRawValues?: boolean,
    }
) => Promise<{file: File, parsedContents: any}>;
```

| Parameter name | Description |
|---|---|
| `label` | A label explaining what file being requested. |
| `options` | **Optional.** Options for the file input. |
| `options.allowedFileTypes` | **Optional.** Which file types can be imported. Like [input#accept](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept), these can be a mix of mime types and extension names, e.g. '.xlsx', 'application/json', 'image/*'. If omitted, all file types are allowed. |
| `options.hasHeaderRow` | **Optional.** Only affects '.xls', '.xlsx', and '.csv' files. If set to true, each parsed row will be an object with keys determined from the header row. If false, each row will be arrays of strings. Defaults to false. |
| `options.useRawValues` | **Optional.** Only affects '.xls', '.xlsx', and '.csv' files. If set to true, the raw cell and header values will be returned as strings. If false, cell and header values will be automatically parsed (e.g. numbers will be converted from string to number type, dates will be converted to Date objects). Defaults to false. |

Prompts the user to import a file.

Returns the imported [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object. If the imported file is a .txt, .xls, .xlsx, .csv, .json, or .xml file, it will also attempt to parse the file and return the parsed contents.

```js
let fileResult = await input.fileAsync(
    'Import a CSV file with header row',
    {
        allowedFileTypes: ['.csv'],
        hasHeaderRow: true
    }
);
output.text(`You uploaded the '${fileResult.file.name}' file.`);
output.table(fileResult.parsedContents);
```


### config (automations only)

```js
function () => Input Object;
```

Returns an object with all input keys mapped to their corresponding values.

```js
let inputConfig = input.config();
console.log(`The value of myKey is ${inputConfig['myKey']}.`);
```


### config (extensions only)

> See also: [Table](/developers/scripting/api/table.md)
> See also: [Field](/developers/scripting/api/field.md)
> See also: [SettingsItem](/developers/scripting/api/config.md#settingsitems)
```js
function (
    settings: {
        title: string,
        description?: string,
        items: Array<SettingsItem>
    }
) => { [key: string]: Table | Field | string | number };
```

| Parameter name | Description |
|---|---|
| `settings` | Settings for your script. |
| `settings.title` | Title of your script. |
| `settings.description` | **Optional.** Description of what your script does.
| `settings.items` | List of items used to generate the script settings UI.

Define the settings for the script. Users of your script can fill in these settings from the extension.

See [Script settings](/developers/scripting/api/config.md) for full details on how to use `input.config()`.