Extensions

Press shift + S to search API reference.

Interface

RecordQueryResultOpts

View source

Used to control what data is loaded in a RecordQueryResult. Used when creating a query result using table/view.selectRecords() and in convenience hooks useRecords.

sorts

Pass an array of sorts to control the order of records. The first sort in the array has the highest priority. If you don't specify sorts, the result will use the inherent order of the source model: the same order you'd see in the main UI for views and linked record fields, and an arbitrary (but stable) order for tables.

Record creation time is used as a tiebreaker: pass an empty array to sort by creation time.

const opts = {
sorts: [
// sort by someField in ascending order...
{field: someField},
// then by someOtherField in descending order
{field: someOtherField, direction: 'desc'},
]
};
const records = useRecords(table, opts);
const queryResult = table.selectRecords(opts);

fields

Generally, it's a good idea to load as little data into your extension as possible - Airtable bases can get pretty big, and we have to keep all that information in memory and up to date if you ask for it. The fields option lets you make sure that only data relevant to you is loaded.

You can specify fields with a Field, by ID, or by name:

const opts = {
fields: [
// we want to only load fieldA:
fieldA,
// the field with this id:
'fldXXXXXXXXXXXXXX',
// and the field named 'Rating':
'Rating',
],
};
const records = useRecords(table, opts);
const queryResult = table.selectRecords(opts);

recordColorMode

Just like a view in Airtable, you can control the colors of records in a field. There are three supported record color modes: none, by a view, and by a select field.

import {recordColoring} from '@airtable/blocks/models';
// No record coloring:
const opts = {
recordColorMode: recordColoring.modes.none(),
};
// Color according to the rules of a view:
const opts = {
recordColorMode: recordColoring.modes.byView(someView),
};
// Color by a single select field:
const opts = {
recordColorMode: recordColoring.modes.bySelectField(someSelectField),
});

You can access view coloring information directly from a RecordQueryResult or a Record, but you can only directly access single select coloring from a RecordQueryResult:

const queryResult = table.selectRecords(opts);
const records = useRecords(table, opts);
// Returns based on opts coloring mode
queryResult.getRecordColor(recordId);
// Returns based on view
// Will throw if you did not pass recordColoring.modes.byView(view) in opts
records[0].getColorInView(view);

Use record.getCellValue(singleSelectField).color to access the color of a single select field for a record.

By default, views will have whichever coloring is set up in Airtable and tables won't have any record coloring:

// these two are the same:
someView.selectRecords();
someView.selectRecords({
recordColorMode: recordColoring.modes.byView(someView),
});
// as are these two:
someTable.selectRecords();
someTable.selectRecords({
recordColorMode: recordColoring.modes.none(),
});
interface RecordQueryResultOpts
fieldsArray<Field | FieldId | string | void | null | false>

The fields (or field names or field ids) to load. Falsey values will be removed.

recordColorModenull | RecordColorMode

How records in this QueryResult should be colored.

sortsArray<SortConfig>

The order in which to sort the query result