How to Set Up a Lookup Field in TableCrafter

Updated July 2026 • 6 min read • By Fahad Murtaza • By Fahad Murtaza

Gravity Forms stores relational data as raw IDs, a driver entry might show 42 where you expect Jane Smith. TableCrafter's lookup field feature resolves those IDs to human-readable labels automatically, right inside your table display, without touching your form or your database schema. This guide walks through the full setup process so your tables show meaningful data instead of numeric noise. 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. 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. TablePress has over 800,000 active installs on WordPress.org (WordPress.org, 2026).

What Is a Lookup Field?

A lookup field is a column configuration that takes a stored value, typically a numeric ID or a machine-readable key, and maps it to a display label pulled from another source. In TableCrafter, this works as a rendering layer: the underlying Gravity Forms entry is never modified. When a user views the table, TableCrafter intercepts the raw value, runs the lookup, and outputs the resolved label instead.

Common use cases include:

• Resolving a WordPress user ID to a display name (e.g., driver assignments)
• Translating a numeric post ID to a post title (e.g., linked job or order records)
• Mapping a Gravity Forms choice value to a friendlier label when the stored value differs from the visible choice
• Joining entries across two forms where one form stores the entry ID of another

How Does Before You Begin Work?

Make sure you have the following in place before configuring a lookup field:

• TableCrafter Pro is installed and activated. Verify under TableCrafter → Settings that your license key is active.
• You have at least one Gravity Forms form with a field that stores an ID or reference value, for example, a User field, a hidden field populated via JavaScript, or a drop-down whose stored value is an ID.
• You have already created a table (or know which table to edit) under TableCrafter → Tables. The table must be connected to the form containing the lookup source field.

How Do I Configure the Lookup Field in the Table Builder?

Open the table you want to modify: go to TableCrafter → Tables, hover over the table row, and click Edit. This opens the drag-and-drop table builder.

In the Columns panel, locate the column that currently displays the raw ID. Click the column to expand its settings. You will see a Field Type dropdown. Change it from Standard to Lookup.

Once Lookup is selected, two additional fields appear:

• Lookup Source, defines where TableCrafter looks up the label. Options include: WordPress Users, Posts / Custom Post Type, Gravity Forms Entries, and Custom Mapping.
• Display Field, which property of the resolved record to show. For WordPress Users this might be Display Name or Email. For posts it might be Post Title.

For example, to resolve a WordPress user ID stored in field 3 of your form to the user's display name:

1. Set Lookup Source to WordPress Users.
2. Set Display Field to Display Name.
3. Confirm the column's Form Field maps to the correct Gravity Forms field ID (the one storing the user ID).

Click Save Table at the top of the builder. TableCrafter writes the column configuration to the database and immediately applies it to the rendered shortcode output.

How Do User Lookup Fields and Inline Editing Work?

Pro When inline editing is enabled on the table, lookup columns get special treatment. Instead of showing a plain text input when a cell enters edit mode, TableCrafter renders a dropdown populated with all valid options from the lookup source. For a WordPress Users lookup, that means a searchable select of every user on the site. For a Gravity Forms Entries lookup, it pulls entry values from the linked form.

This behaviour uses a three-tier fallback system internally:

1. Cache hit, resolved options are cached per-request to avoid redundant queries.
2. Direct query, if the cache misses, TableCrafter queries the appropriate source (WP_User_Query, get_posts, or GFAPI::get_entries).
3. Graceful degradation, if the source returns no results (deleted users, empty form), the raw ID is displayed with a warning indicator rather than a broken input.

When a user selects a new value in the inline dropdown and saves, TableCrafter writes the raw ID back to the Gravity Forms entry using GFAPI::update_entry_field(). The display layer then resolves it again on next render. The stored data stays clean; only the presentation changes.

What Is Custom Mapping: Manual ID-to-Label Tables?

Sometimes your lookup source is not a WordPress object type, it might be a set of internal codes, status flags, or values defined outside WordPress entirely. For these cases, set Lookup Source to Custom Mapping.

A key-value editor appears. Enter each pair on its own row:

1 → Pending Review
2 → In Transit
3 → Delivered
4 → Cancelled

TableCrafter stores this mapping alongside the column config. When a cell value matches a key, the corresponding label is shown. Unmatched values fall through to display the raw value, so existing data is never silently hidden.

Custom mapping pairs well with the Status Badges feature (also Pro). After setting up a custom mapping, open the Badge sub-panel for the same column and assign a color to each label, Pending Review in amber, Delivered in green, and so on. The lookup resolves the ID to the label, and the badge layer converts the label to a color chip, giving you a fully visual status column with zero custom code.

How Does Troubleshooting Common Issues Work?

If your lookup column still shows raw IDs after saving, work through these checks in order:

• License not active: Lookup fields are silently skipped on free-tier installs. Confirm your Pro license is active under TableCrafter → Settings → License.
• Wrong form field mapped: Open the column settings and verify the Form Field selector points to the field that actually holds the ID, not the label or a related field.
• Lookup source mismatch: If the stored value is a Gravity Forms entry ID but Lookup Source is set to WordPress Users, the query will return nothing. Match the source to what is actually stored.
• Caching plugin conflict: Full-page caches (WP Rocket, NitroPack, LiteSpeed Cache) can serve a stale pre-lookup render. Purge the page cache after saving the table config.
• AJAX 403 on inline edit: If the lookup dropdown fails to load options in edit mode, check browser console for a 403 from admin-ajax.php. This usually means the logged-in user lacks the capability required by the table's role-based permission settings. Review Table Settings → Permissions → Allowed Roles.