Extensions

Press shift + S to search API reference.

React hook

useRecords

View source

A hook for working with all of the records (including their colors and cell values) in a particular table, view or query result. Automatically handles loading data and updating your component when the underlying data changes.

This hook re-renders when data concerning the records changes (specifically, when cell values change, the record color changes, and when records are added or removed) - that's useful, but can cause re-renders quite often, meaning useRecordIds or useRecordById could be more appropriate depending on your use case.

Under the hood, this hook creates a TableOrViewQueryResult if passed a table or view. Pass a query result if you want direct access to it (e.g. for queryResult.getRecordById).

Returns a list of records, or null if no model was passed in.

import {useRecords, useBase} from '@airtable/blocks/ui';
function GetRecords() {
const base = useBase();
const table = base.tables[0];
const view = table.views[0];
let records;
// Returns all records in the table
records = useRecords(table);
// Equivalent to the above - useful if you want to reuse the queryResult elsewhere
const queryResult = table.selectRecords();
records = useRecords(queryResult);
// Returns all records for a view
records = useRecords(view)
// Returns all records in a table, only loading data for the specified fields
records = useRecords(table, {fields: ['My field']});
// Returns all records in a table, sorting the records by values in the specified fields
records = useRecords(table, {sorts: [
// sort by 'My field' in ascending order...
{field: 'My field'},
// then by 'My other field' in descending order
{field: 'My other field', direction: 'desc'},
]});
}
import {useRecords, useBase} from '@airtable/blocks/ui';
function RecordList() {
const base = useBase();
const table = base.tables[0];
// grab all the records from that table
const records = useRecords(table);
// render a list of records:
return (
<ul>
{records.map(record => {
return <li key={record.id}>{record.name}</li>
})}
</ul>
);
}

Function signatures

function (tableOrView: Table | View, opts?: RecordQueryResultOpts) => Array<Record>
function (queryResult: AnyQueryResult) => Array<Record>
function (tableOrViewOrQueryResult: null) => null
tableOrViewOrQueryResult

The Table, View or RecordQueryResult you want the records from.