Extensions

Press shift + S to search API reference.

React hook

useWatchable

View source

A React hook for watching data in Airtable models like Table and Record. Each model has several watchable keys that can be used with this hook to have your component automatically re-render when data in the models changes. You can also provide an optional callback if you need to do anything other than re-render when the data changes.

This is a low-level tool that you should only use when you specifically need it. There are more convenient model-specific hooks available:

If you're writing a class component and still want to be able to use hooks, try withHooks.

import {useWatchable} from '@airtable/blocks/ui';
function TableName({table}) {
useWatchable(table, 'name');
return <span>The table name is {table.name}</span>;
}
function ViewNameAndType({view}) {
useWatchable(view, ['name', 'type']);
return <span>The view name is {view.name} and the type is {view.type}</span>;
}
function RecordValuesAndColorInViewIfExists({record, field, view}) {
useWatchable(record, ['cellValues', view ? `colorInView:${view.id}` : null]);
return <span>
The record has cell value {record.getCellValue(field)} in {field.name}.
{view ? `The record has color ${record.getColorInView(view)} in ${view.name}.` : null}
</span>
}
import {useWatchable} from '@airtable/blocks/ui';
function ActiveView({cursor}) {
useWatchable(cursor, 'activeViewId', () => {
alert('active view changed!!!')
});
return <span>Active view id: {cursor.activeViewId}</span>;
}

Function signature

function (models: Watchable<Keys> | ReadonlyArray<Watchable<Keys> | null | undefined> | null | undefined, keys: Keys | ReadonlyArray<Keys | null> | null, callback?: undefined | function (model: Watchable<Keys>, keys: string, args: ...Array<any>) => unknown) => void
models

The model or models to watch.

keys

The key or keys to watch. Non-optional, but may be null.

callback

An optional callback to call when any of the watch keys change.