# Field

**Kind:** Class

Model class representing a field in a table.

```js
import {base} from '@airtable/blocks';

const table = base.getTableByName('Table 1');
const field = table.getFieldByName('Name');
console.log('The type of this field is', field.type);
```

## Properties

### `availableAggregators`

Type: `Array<Aggregator>`

A list of available aggregators given this field's configuration.

```js
const fieldAggregators = myField.availableAggregators;
```

### `config`

Type: `FieldConfig`

The type and options of the field to make type narrowing `FieldOptions` easier.

```js
const fieldConfig = field.config;
if (fieldConfig.type === FieldType.SINGLE_SELECT) {
    return fieldConfig.options.choices;
} else if (fieldConfig.type === FieldType.MULTIPLE_LOOKUP_VALUES && fieldConfig.options.isValid) {
    if (fieldConfig.options.result.type === FieldType.SINGLE_SELECT) {
        return fieldConfig.options.result.options.choices;
    }
}
return DEFAULT_CHOICES;
```

### `description`

Type: `string | null`

The description of the field, if it has one. Can be watched.

```js
console.log(myField.description);
// => 'This is my field'
```

### `id`

Type: `string`

The ID for this model.

### `isComputed`

Type: `boolean`

`true` if this field is computed, `false` otherwise. A field is
"computed" if it's value is not set by user input (e.g. autoNumber, formula,
etc.). Can be watched

```js
console.log(mySingleLineTextField.isComputed);
// => false
console.log(myAutoNumberField.isComputed);
// => true
```

### `isDeleted`

Type: `boolean`

`true` if the model has been deleted, and `false` otherwise.

In general, it's best to avoid keeping a reference to an object past the
current event loop, since it may be deleted and trying to access any data
of a deleted object (other than its ID) will throw. But if you keep a
reference, you can use `isDeleted` to check that it's safe to access the
model's data.

### `isPrimaryField`

Type: `boolean`

`true` if this field is its parent table's primary field, `false` otherwise.
Should never change because the primary field of a table cannot change.

### `name`

Type: `string`

The name of the field. Can be watched.

```js
console.log(myField.name);
// => 'Name'
```

### `options`

Type: `FieldOptions | null`

The configuration options of the field. The structure of the field's
options depend on the field's type. `null` if the field has no options.
Can be watched.

```js
import {FieldType} from '@airtable/blocks/models';

if (myField.type === FieldType.CURRENCY) {
    console.log(myField.options.symbol);
    // => '$'
}
```

### `type`

Type: `FieldType`

The type of the field. Can be watched.

```js
console.log(myField.type);
// => 'singleLineText'
```

## Methods

### `checkPermissionsForUpdateDescription(description?)`

Checks whether the current user has permission to perform the given description update.

Accepts partial input, in the same format as `updateDescriptionAsync`.

Returns `{hasPermission: true}` if the current user can update the specified field,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `description?` (`string | null`) — new description for the field

**Returns:** `PermissionCheckResult`

```js
const updateFieldCheckResult = field.checkPermissionsForUpdateDescription();

if (!updateFieldCheckResult.hasPermission) {
    alert(updateFieldCheckResult.reasonDisplayString);
}
```

### `checkPermissionsForUpdateName(name?)`

Checks whether the current user has permission to perform the given name update.

Accepts partial input, in the same format as `updateNameAsync`.

Returns `{hasPermission: true}` if the current user can update the specified field,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `name?` (`undefined | string`) — new name for the field

**Returns:** `PermissionCheckResult`

```js
const updateFieldCheckResult = field.checkPermissionsForUpdateName();

if (!updateFieldCheckResult.hasPermission) {
    alert(updateFieldCheckResult.reasonDisplayString);
}
```

### `checkPermissionsForUpdateOptions(options?)`

Checks whether the current user has permission to perform the given options update.

Accepts partial input, in the same format as `updateOptionsAsync`.

Returns `{hasPermission: true}` if the current user can update the specified field,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `options?` (`FieldOptions`) — new options for the field

**Returns:** `PermissionCheckResult`

```js
const updateFieldCheckResult = field.checkPermissionsForUpdateOptions();

if (!updateFieldCheckResult.hasPermission) {
    alert(updateFieldCheckResult.reasonDisplayString);
}
```

### `convertStringToCellValue(string)`

Attempt to parse a given string and return a valid cell value for the field's current config.
Returns `null` if unable to parse the given string.

**Parameters:**
- `string` (`string`) — The string to parse.

**Returns:** `unknown`

```js
const inputString = '42';
const cellValue = myNumberField.convertStringToCellValue(inputString);
console.log(cellValue === 42);
// => true
```

### `hasPermissionToUpdateDescription(description?)`

An alias for `checkPermissionsForUpdateDescription(options).hasPermission`.

Checks whether the current user has permission to perform the description update.

Accepts partial input, in the same format as `updateDescriptionAsync`.

**Parameters:**
- `description?` (`string | null`) — new description for the field

**Returns:** `boolean`

```js
const canUpdateField = field.hasPermissionToUpdateDescription();

if (!canUpdateField) {
    alert('not allowed!');
}
```

### `hasPermissionToUpdateName(name?)`

An alias for `checkPermissionsForUpdateName(options).hasPermission`.

Checks whether the current user has permission to perform the name update.

Accepts partial input, in the same format as `updateNameAsync`.

**Parameters:**
- `name?` (`undefined | string`) — new name for the field

**Returns:** `boolean`

```js
const canUpdateField = field.hasPermissionToUpdateName();

if (!canUpdateField) {
    alert('not allowed!');
}
```

### `hasPermissionToUpdateOptions(options?)`

An alias for `checkPermissionsForUpdateOptions(options).hasPermission`.

Checks whether the current user has permission to perform the options update.

Accepts partial input, in the same format as `updateOptionsAsync`.

**Parameters:**
- `options?` (`FieldOptions`) — new options for the field

**Returns:** `boolean`

```js
const canUpdateField = field.hasPermissionToUpdateOptions();

if (!canUpdateField) {
    alert('not allowed!');
}
```

### `isAggregatorAvailable(aggregator)`

Checks if the given aggregator is available for this field.

**Parameters:**
- `aggregator` (`Aggregator | AggregatorKey`) — The aggregator object or aggregator key.

**Returns:** `boolean`

```js
import {aggregators} from '@airtable/blocks/models';
const aggregator = aggregators.totalAttachmentSize;

// Using an aggregator object
console.log(myAttachmentField.isAggregatorAvailable(aggregator));
// => true

// Using an aggregator key
console.log(myTextField.isAggregatorAvailable('totalAttachmentSize'));
// => false
```

### `toString()`

A string representation of the model for use in debugging.

**Returns:** `string`

### `unwatch(keys, callback, context?)`

Unwatch keys watched with `.watch`.

Should be called with the same arguments given to `.watch`.

Returns the array of keys that were unwatched.

**Parameters:**
- `keys` (`WatchableFieldKey | ReadonlyArray<WatchableFieldKey>`) — the keys to unwatch
- `callback` (`object`) — the function passed to `.watch` for these keys
- `context?` (`FlowAnyObject | null`) — the context that was passed to `.watch` for this `callback`

**Returns:** `Array<WatchableFieldKey>`

### `updateDescriptionAsync(description)`

Updates the description for this field.

To remove an existing description, pass `''` as the new description.
`null` is also accepted and will be coerced to `''` for consistency with field creation.

Throws an error if the user does not have permission to update the field, or if an invalid
description is provided.

This action is asynchronous. Unlike updates to cell values, updates to field descriptions are
**not** applied optimistically locally. You must `await` the returned promise before
relying on the change in your extension.

**Parameters:**
- `description` (`string | null`) — new description for the field

**Returns:** `Promise<void>`

```js
await myTextField.updateDescriptionAsync('This is a text field');
```

### `updateNameAsync(name)`

Updates the name for this field.

Throws an error if the user does not have permission to update the field, or if an invalid
name is provided.

This action is asynchronous. Unlike updates to cell values, updates to field name are
**not** applied optimistically locally. You must `await` the returned promise before
relying on the change in your extension.

**Parameters:**
- `name` (`string`) — new name for the field

**Returns:** `Promise<void>`

```js
await myTextField.updateNameAsync('My New Name');
```

### `updateOptionsAsync(options, opts)`

Updates the options for this field.

Throws an error if the user does not have permission to update the field, if invalid
options are provided, if this field has no writable options, or if updates to this field
type is not supported.

Refer to `FieldType` for supported field types, the write format for options, and
other specifics for certain field types.

This action is asynchronous. Unlike updates to cell values, updates to field options are
**not** applied optimistically locally. You must `await` the returned promise before
relying on the change in your extension.

Optionally, you can pass an `opts` object as the second argument. See `UpdateFieldOptionsOpts`
for available options.

**Parameters:**
- `options` (`FieldOptions`) — new options for the field
- `opts` (`UpdateFieldOptionsOpts`) — optional options to affect the behavior of the update

**Returns:** `Promise<void>`

```js
async function addChoiceToSelectField(selectField, nameForNewOption) {
    const updatedOptions = {
        choices: [
            ...selectField.options.choices,
            {name: nameForNewOption},
        ]
    };

    if (selectField.hasPermissionToUpdateOptions(updatedOptions)) {
        await selectField.updateOptionsAsync(updatedOptions);
    }
}
```

### `watch(keys, callback, context?)`

Get notified of changes to the model.

Every call to `.watch` should have a matching call to `.unwatch`.

Returns the array of keys that were watched.

**Parameters:**
- `keys` (`WatchableFieldKey | ReadonlyArray<WatchableFieldKey>`) — the keys to watch
- `callback` (`object`) — a function to call when those keys change
- `context?` (`FlowAnyObject | null`) — an optional context for `this` in `callback`.

**Returns:** `Array<WatchableFieldKey>`