Extensions

Press shift + S to search API reference.

Model

Model class representing a base.

If you want the base model to automatically recalculate whenever the base schema changes, try the useBase hook. Alternatively, you can manually subscribe to changes with useWatchable (recommended) or Base#watch.

import {base} from '@airtable/blocks';
console.log('The name of your base is', base.name);

Members

class Base extends AbstractModel<BaseData, WatchableBaseKey>
readonly activeCollaboratorsArray<CollaboratorData>

The users who have access to this base.

import {base} from '@airtable/blocks';
console.log(base.activeCollaborators[0].email);
readonly colorstring

The color of the base.

import {base} from '@airtable/blocks';
import {Box} from '@airtable/blocks/ui';
const exampleBox = <Box backgroundColor={base.color}> This box's background is the same color as the base background</Box>
readonly idstring

The ID for this model.

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 namestring

The name of the base.

import {base} from '@airtable/blocks';
console.log('The name of your base is', base.name);
readonly tablesArray<Table>

The tables in this base. Can be watched to know when tables are created, deleted, or reordered in the base.

import {base} from '@airtable/blocks';
console.log(`You have ${base.tables.length} tables`);
readonly workspaceIdstring

The workspace id of the base.

import {base} from '@airtable/blocks';
console.log('The workspace id of your base is', base.workspaceId);
checkPermissionsForCreateTable
function (name?: undefined | string, fields?: Array<{
description?: string | null;
name?: undefined | string;
options?: {[key: string]: unknown} | null;
type?: FieldType;
}>
) => PermissionCheckResult
name

name for the table. must be case-insensitive unique

fields

array of fields to create in the table

Checks whether the current user has permission to create a table.

Accepts partial input, in the same format as createTableAsync.

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

const createTableCheckResult = base.checkPermissionsForCreateTable();
if (!createTableCheckResult.hasPermission) {
alert(createTableCheckResult.reasonDisplayString);
}
createTableAsync
function (name: string, fields: Array<{
description?: string | null;
name: string;
options?: {[key: string]: unknown} | null;
type: FieldType;
}>
) => Promise<Table>
name

name for the table. must be case-insensitive unique

fields

array of fields to create in the table: see below for an example. name and type must be specified for all fields, while options is only required for fields that have field options. description is optional and will be '' if not specified or if specified as null.

Creates a new table.

Throws an error if the user does not have permission to create a table, if an invalid table name is provided, or if invalid fields are provided (invalid name, type, options or description).

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

At least one field must be specified. The first field in the fields array will be used as the table's primary field and must be a supported primary field type. Fields must have case-insensitive unique names within the table.

A default grid view will be created with all fields visible.

This action is asynchronous. Unlike new records, new tables are not created optimistically locally. You must await the returned promise before using the new table in your extension.

async function createNewTable() {
const name = 'My new table';
const fields = [
// Name will be the primary field of the table.
{name: 'Name', type: FieldType.SINGLE_LINE_TEXT, description: 'This is the primary field'},
{name: 'Notes', type: FieldType.RICH_TEXT},
{name: 'Attachments', type: FieldType.MULTIPLE_ATTACHMENTS},
{name: 'Number', type: FieldType.NUMBER, options: {
precision: 8,
}},
{name: 'Select', type: FieldType.SINGLE_SELECT, options: {
choices: [
{name: 'A'},
{name: 'B'},
],
}},
];
if (base.hasPermissionToCreateTable(name, fields)) {
await base.createTableAsync(name, fields);
}
}
getCollaborator
function (idOrNameOrEmail: UserId | string) => CollaboratorData | null

The user matching the given ID, name, or email address. Throws if that user does not exist or does not have access to this base. Use getCollaboratorIfExists instead if you are unsure whether a collaborator with the given ID exists and has access to this base.

This method is convenient when building an extension for a specific base, but for more generic extensions the best practice is to use the getCollaboratorById method instead.

getCollaboratorById
function (collaboratorId: UserId) => CollaboratorData
collaboratorId

The ID of the user.

The user matching the given ID. Throws if that user does not exist or does not have access to this base. Use getCollaboratorByIdIfExists instead if you are unsure whether a collaborator with the given ID exists and has access to this base.

getCollaboratorByIdIfExists
function (collaboratorId: UserId) => CollaboratorData | null
collaboratorId

The ID of the user.

The user matching the given ID, or null if that user does not exist or does not have access to this base.

getCollaboratorIfExists
function (idOrNameOrEmail: UserId | string) => CollaboratorData | null

The user matching the given ID, name, or email address. Returns null if that user does not exist or does not have access to this base.

This method is convenient when building an extension for a specific base, but for more generic extensions the best practice is to use the getCollaboratorByIdIfExists method instead.

getMaxRecordsPerTable
function () => number

Returns the maximum number of records allowed in each table of this base.

getTable
function (tableIdOrName: TableId | string) => Table
tableIdOrName

The ID or name of the table you're looking for.

The table matching the given ID or name. Throws if no matching table exists within this base. Use getTableIfExists instead if you are unsure whether a table exists with the given name/ID.

This method is convenient when building an extension for a specific base, but for more generic extensions the best practice is to use the getTableById or getTableByName methods instead.

getTableById
function (tableId: string) => Table
tableId

The ID of the table.

The table matching the given ID. Throws if that table does not exist in this base. Use getTableByIdIfExists instead if you are unsure whether a table exists with the given ID.

getTableByIdIfExists
function (tableId: string) => Table | null
tableId

The ID of the table.

The table matching the given ID, or null if that table does not exist in this base.

getTableByName
function (tableName: string) => Table
tableName

The name of the table you're looking for.

The table matching the given name. Throws if no table exists with that name in this base. Use getTableByNameIfExists instead if you are unsure whether a table exists with the given name.

getTableByNameIfExists
function (tableName: string) => Table | null
tableName

The name of the table you're looking for.

The table matching the given name, or null if no table exists with that name in this base.

getTableIfExists
function (tableIdOrName: TableId | string) => Table | null
tableIdOrName

The ID or name of the table you're looking for.

The table matching the given ID or name. Returns null if no matching table exists within this base.

This method is convenient when building an extension for a specific base, but for more generic extensions the best practice is to use the getTableByIdIfExists or getTableByNameIfExists methods instead.

hasPermissionToCreateTable
function (name?: undefined | string, fields?: Array<{
description?: string | null;
name?: undefined | string;
options?: {[key: string]: unknown} | null;
type?: FieldType;
}>
) => boolean
name

name for the table. must be case-insensitive unique

fields

array of fields to create in the table

An alias for checkPermissionsForCreateTable(name, fields).hasPermission.

Checks whether the current user has permission to create a table.

Accepts partial input, in the same format as createTableAsync.

const canCreateTable = table.hasPermissionToCreateTable();
if (!canCreateTable) {
alert('not allowed!');
}
toString
function () => string

A string representation of the model for use in debugging.

unwatch
function (keys: WatchableBaseKey | ReadonlyArray<WatchableBaseKey>, callback: function (model: this, key: WatchableBaseKey, args: ...Array<any>) => unknown, context?: FlowAnyObject | null) => Array<WatchableBaseKey>
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.

watch
function (keys: WatchableBaseKey | ReadonlyArray<WatchableBaseKey>, callback: function (model: this, key: WatchableBaseKey, args: ...Array<any>) => unknown, context?: FlowAnyObject | null) => Array<WatchableBaseKey>
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.