How to Map Airtable Fields to Table Columns in TableCrafter

Updated July 2026 • 7 min read • By Fahad Murtaza

Airtable supports over a dozen field types, and each one behaves differently when pulled into TableCrafter. This guide covers exactly how TableCrafter renders Single line text, Long text, Number, Single select, Multi-select, Date, Attachment, Formula, and Linked record fields, including which are editable inline and which are read-only. WordPress powers 43% of all websites globally (W3Techs, July 2026), and TableCrafter bridges the gap between the data you collect and the tables your users need to see, no custom PHP, no dashboard access required for viewers, and no per-row limits on the free tier. The free version on WordPress.org supports CSV, JSON, Google Sheets, and Excel. Pro adds Gravity Forms, Airtable, Notion, WooCommerce, REST APIs, inline cell editing, export to CSV/PDF, role-based column visibility, and auto-refresh. Every table embeds on any page with a [tablecrafter] shortcode or the native Gutenberg block. Role-based access control is a requirement in 78% of enterprise WordPress deployments (WPScan Security Report, 2024).

How Does Field Mapping Work?

When you connect an Airtable base to TableCrafter and click Test Connection, TableCrafter reads the schema of your table from the Airtable Metadata API. The response includes each field's name, declared type, and option configuration such as the color-coded choices for select fields. TableCrafter passes your personal access token as a Bearer header on this request. The PAT is stored encrypted at rest: the plugin derives a 256-bit AES-256-CBC key from your WordPress AUTH_KEY salt, encrypts the token with a fresh random 16-byte initialization vector, and writes the envelope to the options table. It is never stored as plain text. Subsequent page loads read from a WordPress transient (key gt_airtable_table_{table_id}) with a configurable TTL that defaults to 30 minutes, clamped between 5 minutes and 24 hours.

You can override the auto-detected column type in the Columns configuration panel. This is useful when the Airtable-declared type does not match your intended rendering: displaying a singleLineText field that always holds image URLs as an Image column so TableCrafter renders thumbnails, or promoting a formula field returning an ISO date string to a Date column so date-range filtering activates correctly. Any Airtable field type not listed in the internal mapping table defaults to a plain text column, so unknown future field types degrade gracefully.

This step completes the connection between your data source and the TableCrafter table engine. Once saved, the plugin caches the connection credentials in the WordPress options table and uses them on every subsequent page load. If you update the source configuration later — for example, rotating an API key or changing a sheet URL — return to this step, enter the new value, and save again. The table updates immediately on next load without any shortcode changes.

How Does Field Type Reference Work?

Single Line Text

Airtable API type: singleLineText

The Airtable REST API returns a singleLineText field as a plain JSON string in the record's fields object, for example "Name": "Acme Corp". If the cell is blank in Airtable, the key is omitted from the response entirely rather than returned as an empty string; TableCrafter normalizes missing keys to an empty cell so no rendering error occurs. The field maps to the text column type and renders as unstyled plain text. In edit mode, clicking the cell opens a single-line text input; saving sends a PATCH request to https://api.airtable.com/v0/{base_id}/{table_id}/{record_id} with the updated value. A client-side sliding-window rate limiter (five requests per second per base) queues rapid saves rather than letting them hit Airtable's 429 limit. The global search bar applies a case-insensitive substring match across all visible singleLineText cells simultaneously; per-column text filters narrow to a single column using the same match. Sort order is lexicographic. Gotcha: a singleLineText cell containing a numeric string such as "007" sorts as text, placing it before "10". Override the column type to Number in the builder if you need numeric sort behavior on a text field that stores numbers.

• Inline editing: Yes
• Search: Yes
• Filter type: Text contains

Long Text (Rich Text)

Airtable API type: multilineText or richText

Renders as a truncated text cell with a configurable character limit. TableCrafter does not render full Markdown or rich text formatting inline in the table cell, it strips formatting tags and shows plain text. If you need formatted output, use a detail panel or link to a separate page.

The Airtable API distinguishes two separate types here: multilineText for plain multi-line text and richText for Markdown-formatted content. Both map to the text column type in the field mapper, since the table cell is not designed to render HTML or Markdown. Both are stored in the cached row set as the raw string returned by the API. For richText fields, that string includes Markdown syntax characters such as asterisks and brackets, which appear as literal characters in the cell rather than rendered formatting. The global search bar matches against the full raw string, so search terms contained inside Markdown-formatted spans are still findable. Because both types are stored and rendered as text, both participate in the per-column Text Contains filter when that filter is enabled on the column.

• Inline editing: Yes (plain text only, formatting lost on save)
• Search: Yes
• Filter type: Text contains

Number

Airtable API type: number

The number type returns a JSON numeric value such as 42 or 3.14159, or the field key is omitted from the response when the cell is empty. Several Airtable field types all map to the same number column in TableCrafter: number, currency, percent, duration, and rating are all treated as numeric columns and support numeric sort and range filtering. The exception is autoNumber, which also maps to the number column type but is always read-only because Airtable manages its value automatically and the REST API rejects writes to it. TableCrafter respects the decimal precision configured in Airtable, so a field set to two decimal places returns 14.25, not 14.25000. You can apply a display prefix or suffix in the column settings to show currency symbols or percentage signs without modifying the stored numeric value. Sorting is numeric rather than lexicographic, so 10 sorts after 9 as expected. For write-back, TableCrafter sends the numeric value as a JSON number in the PATCH body. Gotcha: the range filter shows minimum and maximum inputs, but empty cells are excluded from results once either bound is set, even if the empty cell would normally appear in an unfiltered view.

• Inline editing: Yes (numeric input)
• Search: No (use range filter)
• Filter type: Numeric range (min / max inputs)

Single Select

Airtable API type: singleSelect

The singleSelect type returns the selected option's name as a plain string, for example "Status": "In Progress". The Airtable Metadata API schema also includes the full list of configured options along with their assigned hex color codes. TableCrafter reads those color values during schema fetch and maps each to a CSS badge class, so the cell renders as a colored pill label that visually matches what users see inside Airtable. If Airtable does not return color data for an option, the badge falls back to the default neutral style. For filtering, TableCrafter builds a dropdown from the distinct values found in the current cached row set rather than from the schema list. This means options that exist in the Airtable schema but have no matching rows are excluded from the filter dropdown automatically, keeping the control uncluttered. Selecting an option narrows the table to rows where that column exactly matches the selected value. In edit mode, clicking the cell opens a dropdown populated from the schema's option list, so only valid Airtable options are selectable. Sort order is alphabetical by option name. Gotcha: if a new option is added in Airtable after the table's row cache was last populated, that option will not appear in the filter dropdown until the cache expires or is force-refreshed from the TableCrafter admin.

• Inline editing: Yes (dropdown populated with Airtable's configured options)
• Search: No
• Filter type: Dropdown select

Multi-Select

Airtable API type: multipleSelects

The multipleSelects type returns a JSON array of option name strings, for example "Tags": ["Urgent", "Q3", "Customer-Facing"]. TableCrafter renders each value in the array as a separate pill badge in the cell, with colors sourced from the Airtable schema where available. Internally, the cached row set stores multi-select values as comma-separated strings. The filter service splits these strings on commas to recover individual values before running filter or sort logic, applying case-insensitive matching throughout. For filtering, TableCrafter builds a multi-select dropdown from the distinct values found across all rows, alphabetically ordered. Visitors can select one or more values simultaneously. The filter applies OR logic within the control: a row is shown if its cell contains any one of the selected values. Across separate filter controls on the same table, the logic is AND: a row must pass every active filter to appear in results. Sort order is determined by the first value in the array, alphabetically; empty cells sort last in ascending order. In edit mode, the cell presents a multi-select input loaded from the schema's option list. Gotcha: Airtable's own option names cannot contain commas, so the comma-split is safe for native multi-select data. The edge case only arises when data was imported from an external source that embeds commas inside option strings.

• Inline editing: Yes (multi-select input with Airtable's configured options)
• Search: No
• Filter type: Multi-select dropdown

Date and Date/Time

Airtable API type: date or dateTime

Airtable returns dates in ISO 8601 format. TableCrafter formats them using the date format configured in your TableCrafter global settings (for example MM/DD/YYYY or DD MMM YYYY). Sorting on date columns is chronological. The filter renders as a date range picker with From and To inputs.

Beyond the basic date and dateTime types, Airtable has two additional date-adjacent field types that TableCrafter also maps to the date column: createdTime and lastModifiedTime. Both are always read-only in TableCrafter because Airtable sets them automatically and the REST API rejects writes to them. Including a createdTime or lastModifiedTime column activates the date range filter on it the same way as a manually managed date field, which lets visitors filter by when records were created or last edited. One practical detail: changing the display format in settings does not affect sort behavior. Sorting always uses ISO 8601 chronological ordering internally, so MM/DD/YYYY and DD MMM YYYY display formats produce identical sort results. The display format controls only how the date string appears in the cell.

• Inline editing: Yes (date picker)
• Search: No
• Filter type: Date range

Checkbox

Airtable API type: checkbox

The checkbox Airtable type returns a JSON boolean when checked, but omits the field key entirely for unchecked boxes rather than returning false. TableCrafter treats a missing checkbox key as unchecked, which matches Airtable's own behavior and means you can reliably distinguish between "checked" and "not checked" without additional null handling. The field maps to the toggle column type internally. In read-only mode, the cell displays a checkmark icon for true and a dash for a missing or false value. TableCrafter intentionally does not render a live interactive checkbox input in read mode, because a clickable checkbox element implies editability and can cause accidental state changes on tables where editing is not intended. In edit mode, clicking anywhere in the cell toggles the boolean and immediately sends a PATCH request to Airtable. The same sliding-window rate limiter (five requests per second per base) applies, so rapid toggles queue rather than triggering 429 responses. The boolean filter is a three-way dropdown: "Yes" shows only checked rows, "No" shows only unchecked rows, and "Either" disables the filter. The global search bar does not perform substring matching on boolean cells. Gotcha: unchecked fields are omitted from the API response entirely, not returned as false. Code outside TableCrafter that reads this data must handle the missing key.

• Inline editing: Yes (toggle on click)
• Search: No
• Filter type: Boolean (Yes / No / Either)

Attachment

Airtable API type: multipleAttachments

Airtable returns attachment fields as an array of objects containing a URL, filename, and MIME type. TableCrafter renders the first attachment. If the attachment is an image (MIME type image/*), TableCrafter renders a thumbnail. For other file types, it renders a download link showing the filename.

The multipleAttachments Airtable type maps to the image column type in the field mapper's default mapping table. This happens automatically when TableCrafter reads the field schema; no manual column type override is required. The thumbnail rendered in the cell uses the URL from the first attachment object in the array; if a record has multiple attachments, only the first is shown. Airtable attachment URLs are signed and expire after a short period, which means cached rows can contain URLs that have already expired. This is a known characteristic of the Airtable attachment model: if the table shows broken image thumbnails, force-refresh the transient cache from the TableCrafter admin to fetch fresh signed URLs. Attachment fields are always read-only regardless of the table's edit mode, because the Airtable REST API does not accept file upload payloads through the record PATCH endpoint used for write-back.

• Inline editing: No (read-only; uploading files via TableCrafter is not supported)
• Search: No
• Filter type: None

Formula

Airtable API type: formula

Airtable computes formula fields server-side and returns the computed value in the API response. TableCrafter receives and displays the result, it does not see or evaluate the formula expression itself. The rendered type depends on the formula output: a formula that returns a number is treated as a number column; a formula returning text is treated as a text column.

The field mapper assigns formula to the text column type by default and marks it read-only. This means a formula column that returns a numeric result uses text-style alphabetic sorting and a Text Contains filter rather than numeric range filtering, unless you manually override the column type to Number in the builder. The same applies to autoNumber: it maps to the number type and supports numeric sort and range filtering, but is always read-only because Airtable manages its value automatically and the REST API rejects writes to autoNumber fields. For a formula that returns an ISO 8601 date string, override the column type to Date to activate the date range picker filter.

• Inline editing: No (always read-only; formula values are computed by Airtable)
• Search: Depends on output type
• Filter type: Depends on output type

Rollup and Count

Airtable API type: rollup, count

The rollup type aggregates values from a linked table using a formula such as SUM(), MAX(), or CONCATENATE(). The count type simply counts the number of linked records in a related table. Both return computed values that Airtable evaluates server-side before including them in the API response; TableCrafter receives only the result, not the formula expression or the linked data behind it. The lookup field type follows the same pattern, fetching a specific field value from a linked record. All three types are always read-only in TableCrafter because the Airtable REST API does not permit clients to write to computed fields. The field mapper categorizes rollup, count, and lookup as the text column type by default. A critical consequence: if a rollup returns a numeric value such as a sum or maximum, numeric range filtering does not activate automatically because the initial column type is text. To enable a minimum and maximum range filter on a numeric rollup column, open the column in the builder and manually override the column type from Auto to Number. Once overridden, sorting also becomes numeric rather than lexicographic. Gotcha: if you forget to override the column type and see alphabetic sort on what appears to be a number column, this is almost certainly the cause.

• Inline editing: No
• Filter type: Numeric range (for numeric rollups)

Linked Record

Airtable API type: multipleRecordLinks

Linked record fields return an array of record IDs from another table in the same base. By default, Airtable's API returns only the record IDs unless you request additional field data. TableCrafter resolves linked records to their primary field (the first field in the linked table) and displays those values as a comma-separated list in the cell.

• Inline editing: No (linked records cannot be modified via TableCrafter)
• Search: Yes (searches resolved primary field values)
• Filter type: Text contains

URL

Airtable API type: url

The url Airtable type returns a plain string containing the full URL, for example "Website": "https://example.com". The field key is omitted from the API response when the cell is empty; TableCrafter renders an empty cell in that case. The field maps to the url column type, which renders the cell as an HTML anchor element opening in a new browser tab via target="_blank". The visible link text defaults to the raw URL string. If you want a friendlier label such as "View Report" or "Open Link", set a static override label in the column settings in the builder; the label applies identically across all rows in that column. Per-row labels, where each row shows different link text, require a separate text field in Airtable to hold the label and a column type override in TableCrafter. In edit mode, clicking the URL cell opens a plain text input. TableCrafter sends the updated string to Airtable via PATCH without format-validating it at the plugin level, so any string value is accepted by the API. The global search bar and per-column text filters both apply case-insensitive substring matching to the raw URL string. Gotcha: if the field is empty in Airtable, no anchor tag is rendered; the cell is genuinely empty rather than showing a placeholder link.

• Inline editing: Yes (text input for the URL)
• Search: Yes
• Filter type: Text contains

Email and Phone

Airtable API types: email, phoneNumber

The email Airtable type returns a plain string containing an email address, for example "Contact": "hello@example.com". TableCrafter maps it to the dedicated email column type and renders the cell as a mailto: hyperlink, so clicking the address opens the visitor's default mail client with the To field pre-filled. The phoneNumber type similarly returns a plain string and is mapped to the text column type. TableCrafter preserves the original Airtable field type as source_type metadata alongside the mapped column type, which allows the rendering layer to apply phone-specific formatting such as tel: link wrapping where the feature is wired for that source type. Both fields are fully searchable via the global search bar and per-column text filters using case-insensitive substring matching, so typing a country code prefix in a per-column filter returns all rows matching that prefix. This makes it practical to filter a contacts table to a specific region by dialing prefix without creating a separate region field. In edit mode, both fields are editable inline and saves are sent via PATCH to the Airtable REST API. Gotcha: neither Airtable nor TableCrafter validates email or phone format at the REST API level; any non-empty string is accepted. Enforce format requirements at the Airtable or Gravity Forms form layer.

• Inline editing: Yes
• Search: Yes
• Filter type: Text contains

How Does Overriding Auto-Detected Column Types Work?

TableCrafter's auto-detection is accurate for most field types, but you may want to override it in specific situations:

• A Single line text field that always contains image URLs: override to Image column type so TableCrafter renders a thumbnail instead of raw text.
• A Number field representing a percentage: set a suffix of % in column settings.
• A Formula field returning a date: set the column type to Date so date range filtering works correctly.

To override, open the table configuration, find the column, and change the Column Type dropdown from Auto to the desired type.

If this step produces unexpected output, check the source data directly in the connected system. TableCrafter passes data through without modification — if a cell displays an unexpected value, the source record contains that value. Use the TableCrafter debug log (Settings > Advanced > Debug Mode) to trace the exact query sent to the source and the raw response received, which narrows the diagnosis to either a source-side or rendering-side issue.

How Does Read-Only vs. Editable Fields at a Glance Work?

The distinction between always-read-only and conditionally-editable fields comes from the field mapper's internal READONLY_TYPES list. The field types that are always read-only regardless of the table's edit mode setting are: formula, rollup, lookup, count, autoNumber, createdTime, and lastModifiedTime. Each of these is computed or managed by Airtable itself, and the REST API returns an error if a client attempts to PATCH a record's value for any of them. For all other field types, the editable state depends on the table configuration and whether edit="true" is present in the shortcode. Write-back sends a PATCH request to the Airtable REST API, and the personal access token must carry the data.records:write scope for saves to succeed. A token missing that scope will cause all save attempts to return a 403 error at the API level.

Enable edit mode in the shortcode with edit="true":

[tablecrafter id="1" edit="true"]

Ensure your Airtable personal access token includes the data.records:write scope when using inline editing.

The data source connection is checked on each page load. If the source becomes unavailable — for example, if an Airtable API key is revoked or a Google Sheet is unpublished — TableCrafter displays a configurable error message rather than an empty table, so site visitors receive feedback rather than a blank page.

The shortcode accepts all column and filter settings defined in the table builder as defaults, but you can override individual parameters inline. For example, `[tablecrafter id="1" per_page="25"]` overrides the default rows-per-page setting for this specific embed without changing the saved table configuration. This lets you reuse one table definition across multiple pages with different display requirements.