Extensions

Press shift + S to search API reference.

Model

Model class containing information about the state of the user's current interactions in Airtable - specifically, their active table, active view, selected records and selected fields. Also allows you to set the active table and active view.

Selected records and fields are not loaded by default and the cursor must be loaded with useLoadable to access them.

import {useCursor, useWatchable} from '@airtable/blocks/ui';
function ActiveTableAndView() {
const cursor = useCursor();
return (
<div>
Active table: {cursor.activeTableId}
<br />
Active view: {cursor.activeViewId}
</div>
);
}
import {useCursor, useLoadable, useWatchable} from '@airtable/blocks/ui';
function SelectedRecordAndFieldIds() {
const cursor = useCursor();
// load selected records and fields
useLoadable(cursor);
// re-render whenever the list of selected records or fields changes
useWatchable(cursor, ['selectedRecordIds', 'selectedFieldIds']);
return (
<div>
Selected records: {cursor.selectedRecordIds.join(', ')}
<br />
Selected fields: {cursor.selectedFieldIds.join(', ')}
</div>
);
}

Members

class Cursor extends AbstractModelWithAsyncData<CursorData, WatchableCursorKey>
readonly activeTableIdTableId | null

The currently active table ID. Can be null when the active table has changed and is not yet loaded, and can also refer to a table that is not yet loaded.

When fetching the Table, use base.getTableByIdIfExists(cursor.activeTableId) and check the return value is not null to be resilient to those cases.

Can be watched.

readonly activeViewIdViewId | null

The currently active view ID. This will always be a view belonging to activeTableId. Can be null when the active view has changed and is not yet loaded, and can also refer to a view that is not yet loaded.

When fetching the View, use table.getViewByIdIfExists(cursor.activeViewId) and check the return value is not null to be resilient to those cases.

Can be watched.

readonly idstring

The ID for this model.

readonly isDataLoadedboolean
readonly isDeletedboolean
readonly selectedFieldIdsArray<RecordId>

The field IDs of all currently selected fields, or an empty array if no fields are selected.

Not loaded by default: you must load cursor data with useLoadable(cursor) (recommended) or cursor.loadDataAsync() before use.

Can be watched.

readonly selectedRecordIdsArray<RecordId>

The record IDs of all currently selected records, or an empty array if no records are selected.

Not loaded by default. You must load cursor data with useLoadable(cursor) (recommended) or cursor.loadDataAsync() before use.

Can be watched.

isRecordSelected
function (recordOrRecordId: Record | string) => boolean
recordOrRecordId

The record or record ID to check for.

Checks whether a given record is selected.

Selected records are not loaded by default. You must load cursor data with useLoadable(cursor) (recommended) or cursor.loadDataAsync() before use.

loadDataAsync
function () => Promise<void>

Will cause all the async data to be fetched and retained. Every call to loadDataAsync should have a matching call to unloadData.

Returns a Promise that will resolve once the data is loaded.

setActiveTable
function (tableOrTableId: Table | TableId) => void
tableOrTableId

The target table or table ID to set as active in the Airtable main page.

Sets the specified table to active in the Airtable UI. If the extension installation or extensions pane is fullscreen, fullscreen mode will be exited.

setActiveView
function (tableOrTableId: Table | TableId, viewOrViewId: View | ViewId) => void
tableOrTableId

The table or table ID that the target view belongs to.

viewOrViewId

The target view or view ID to set as active in the Airtable main page.

Sets the specified view (and corresponding table) to active in the Airtable UI. If the extension installation or extensions pane is fullscreen, fullscreen mode will be exited.

toString
function () => string

A string representation of the model for use in debugging.

unloadData
function () => void
unwatch
function (keys: WatchableCursorKey | ReadonlyArray<WatchableCursorKey>, callback: FlowAnyFunction, context?: FlowAnyObject | null) => Array<WatchableCursorKey>

Unwatching a key that needs to load data asynchronously will automatically cause the data to be released. Once the data is available, the callback will be called.

watch
function (keys: WatchableCursorKey | ReadonlyArray<WatchableCursorKey>, callback: FlowAnyFunction, context?: FlowAnyObject | null) => Array<WatchableCursorKey>

Watching a key that needs to load data asynchronously will automatically cause the data to be fetched. Once the data is available, the callback will be called.