Extensions

Press shift + S to search API reference.

Model

Model class representing a field in a table.

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);

Members

class Field extends AbstractModel<FieldData, WatchableFieldKey>
readonly availableAggregatorsArray<Aggregator>

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

const fieldAggregators = myField.availableAggregators;
readonly configFieldConfig

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

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;
readonly descriptionstring | null

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

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

The ID for this model.

readonly isComputedboolean

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

console.log(mySingleLineTextField.isComputed);
// => false
console.log(myAutoNumberField.isComputed);
// => true
readonly isDeletedboolean

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.

readonly isPrimaryFieldboolean

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.

readonly namestring

The name of the field. Can be watched.

console.log(myField.name);
// => 'Name'
readonly optionsFieldOptions | 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.

import {FieldType} from '@airtable/blocks/models';
if (myField.type === FieldType.CURRENCY) {
console.log(myField.options.symbol);
// => '$'
}
readonly typeFieldType

The type of the field. Can be watched.

console.log(myField.type);
// => 'singleLineText'
checkPermissionsForUpdateDescription
function (description?: string | null) => PermissionCheckResult
description

new description for the field

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.

const updateFieldCheckResult = field.checkPermissionsForUpdateDescription();
if (!updateFieldCheckResult.hasPermission) {
alert(updateFieldCheckResult.reasonDisplayString);
}
checkPermissionsForUpdateName
function (name?: undefined | string) => PermissionCheckResult
name

new name for the field

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.

const updateFieldCheckResult = field.checkPermissionsForUpdateName();
if (!updateFieldCheckResult.hasPermission) {
alert(updateFieldCheckResult.reasonDisplayString);
}
checkPermissionsForUpdateOptions
function (options?: FieldOptions) => PermissionCheckResult
options

new options for the field

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.

const updateFieldCheckResult = field.checkPermissionsForUpdateOptions();
if (!updateFieldCheckResult.hasPermission) {
alert(updateFieldCheckResult.reasonDisplayString);
}
convertStringToCellValue
function (string: string) => unknown
string

The string to parse.

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.

const inputString = '42';
const cellValue = myNumberField.convertStringToCellValue(inputString);
console.log(cellValue === 42);
// => true
hasPermissionToUpdateDescription
function (description?: string | null) => boolean
description

new description for the field

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.

const canUpdateField = field.hasPermissionToUpdateDescription();
if (!canUpdateField) {
alert('not allowed!');
}
hasPermissionToUpdateName
function (name?: undefined | string) => boolean
name

new name for the field

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.

const canUpdateField = field.hasPermissionToUpdateName();
if (!canUpdateField) {
alert('not allowed!');
}
hasPermissionToUpdateOptions
function (options?: FieldOptions) => boolean
options

new options for the field

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.

const canUpdateField = field.hasPermissionToUpdateOptions();
if (!canUpdateField) {
alert('not allowed!');
}
isAggregatorAvailable
function (aggregator: Aggregator | AggregatorKey) => boolean
aggregator

The aggregator object or aggregator key.

Checks if the given aggregator is available for this field.

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
function () => string

A string representation of the model for use in debugging.

unwatch
function (keys: WatchableFieldKey | ReadonlyArray<WatchableFieldKey>, callback: function (model: this, key: WatchableFieldKey, args: ...Array<any>) => unknown, context?: FlowAnyObject | null) => Array<WatchableFieldKey>
keys

the keys to unwatch

callback

the function passed to .watch for these keys

context

the context that was passed to .watch for this callback

Unwatch keys watched with .watch.

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

Returns the array of keys that were unwatched.

updateDescriptionAsync
function (description: string | null) => Promise<void>
description

new description for the field

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.

await myTextField.updateDescriptionAsync('This is a text field');
updateNameAsync
function (name: string) => Promise<void>
name

new name for the field

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.

await myTextField.updateNameAsync('My New Name');
updateOptionsAsync
function (options: FieldOptions, opts: UpdateFieldOptionsOpts = {}) => Promise<void>
options

new options for the field

opts

optional options to affect the behavior of the update

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.

async function addChoiceToSelectField(selectField, nameForNewOption) {
const updatedOptions = {
choices: [
...selectField.options.choices,
{name: nameForNewOption},
]
};
if (selectField.hasPermissionToUpdateOptions(updatedOptions)) {
await selectField.updateOptionsAsync(updatedOptions);
}
}
watch
function (keys: WatchableFieldKey | ReadonlyArray<WatchableFieldKey>, callback: function (model: this, key: WatchableFieldKey, args: ...Array<any>) => unknown, context?: FlowAnyObject | null) => Array<WatchableFieldKey>
keys

the keys to watch

callback

a function to call when those keys change

context

an optional context for this in callback.

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.