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 modequeryResult.getRecordColor(recordId);// Returns based on view// Will throw if you did not pass recordColoring.modes.byView(view) in optsrecords[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(),});