What Is a Lookup Field in TableCrafter and When to Use One

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

When your Gravity Forms entries store raw IDs instead of human-readable labels, your data tables can look like a wall of numbers that means nothing to the people reading them. TableCrafter's lookup field feature solves this by resolving those IDs into meaningful text at display time, without touching your underlying form data. If you've ever seen a column full of user IDs, post IDs, or numeric codes and wondered how to show names instead, this guide is for you. 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. Conditional logic fields in Gravity Forms are used by 73% of complex form builders (Gravity Forms user survey, 2024).

Why Lookup Fields Solve?

Gravity Forms stores relational data as IDs by nature. A field that lets a user select a driver stores that driver's WordPress user ID. A field tied to a product stores a post ID. A dropdown backed by a custom list stores the numeric key, not the label. This is correct behavior for a database, IDs are stable, labels are not, but it creates a readability problem the moment you surface that data in a table.

Without lookup resolution, a column titled "Assigned Driver" might display values like 42, 7, and 138. A manager reading that table has no idea which number corresponds to which person. They'd need to cross-reference another system, which defeats the purpose of having a live data table in the first place.

Lookup fields tell TableCrafter: "when you encounter this value in this column, go find the matching label and show that instead." The original ID is preserved in the database. The table display shows the resolved text.

How Lookup Fields Work Under the Hood?

When TableCrafter renders a table row, it checks each column's configuration. If a column is marked as a lookup field, the rendering engine runs a resolution pass before outputting the cell value. The resolution logic uses a three-tier fallback system:

1. Direct lookup source. If you've configured an explicit source (such as WordPress users, a custom post type, or a static map), TableCrafter queries that source for a label matching the stored ID and uses that result.
2. Field metadata fallback. If no explicit source is configured but the underlying Gravity Forms field has choices (dropdown, radio, checkbox), TableCrafter reads those choice labels from the form definition and maps them to the stored values.
3. Raw value passthrough. If neither of the above resolves the value, TableCrafter renders the raw stored value rather than leaving the cell blank. This ensures tables never silently lose data.

This fallback architecture means that in many cases, lookup resolution works automatically for choice-based fields without any extra configuration. You only need to set up an explicit lookup source when the stored value is a foreign key that points to something outside the form itself, such as a WordPress user ID or a post from a different content type.

All resolution happens server-side during the AJAX table fetch (the same wp-admin/admin-ajax.php call that handles filtering, sorting, and pagination), so the resolved labels appear immediately in the rendered table without any client-side JavaScript gymnastics.

What Are the Common Use Cases?

Lookup fields cover a wide range of real-world scenarios. Here are the most frequent ones:

• WordPress user IDs → display names. Any form that captures a user via a User field or a hidden field populated with current_user_id will store a numeric ID. A lookup field configured to resolve against WordPress users will show "Jane Smith" instead of 42. This is the most common use case in role-based workflows like load tracking, task assignment, and order management.
• Post or page IDs → titles. If your form includes a field that stores a post ID (for example, a linked product, a job posting, or a location record), a lookup field can resolve that ID to the post title, making the table readable without navigating away.
• Dropdown stored values → labels. Gravity Forms dropdowns store the "value" attribute of each choice, which is often a short code or number. Lookup fields using the field metadata fallback will automatically show the full label text that the user saw when filling out the form.
• Custom taxonomy term IDs → term names. Forms built around custom taxonomies often store term IDs. A lookup field pointing at the appropriate taxonomy resolves those to readable term names in the table.
• Static code maps. Sometimes you have a finite set of codes (status codes, department abbreviations, priority levels) that aren't stored anywhere in WordPress. You can configure a static key-value map directly in the column settings so TableCrafter knows that P1 means "Critical" and P3 means "Low".

How Do I Set Up a Lookup Field in the Table Builder?

Configuration happens inside the TableCrafter admin interface at TableCrafter → Tables → Add New (or edit an existing table). Once you've added a column and selected the Gravity Forms field it maps to, look for the Display Type or Column Type setting for that column. 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.

The steps are:

1. Open your table in the builder and locate the column you want to make a lookup column.
2. Change the column's display type to Lookup.
3. Select the lookup source from the dropdown. Options typically include: WordPress Users, Post Type (with a post type selector), Taxonomy Terms, Form Choices (auto, using field metadata), and Custom Map (manual key-value pairs).
4. Save the table configuration.

The table will immediately begin resolving values on the next page load or AJAX refresh. No shortcode changes are required, the same shortcode you're already using handles the resolved display automatically:

[tablecrafter id="X"]
[tablecrafter id="X"]
[tablecrafter id="X"]

All three shortcode aliases map to the same handler, so whichever you've been using continues to work.

How Do Lookup Fields and Filtering Work?

One subtlety worth knowing: TableCrafter's advanced filter panel operates on the stored values in the Gravity Forms entries database, not on the resolved display labels. This is intentional, filtering on stored values is fast and consistent, but it means your filter inputs need to match what's actually stored.

To make this transparent to end users, TableCrafter automatically converts lookup columns to dropdown filters in the filter panel when advanced filters are enabled. Instead of typing a raw ID, the user sees a dropdown populated with the resolved labels. Selecting "Jane Smith" from that dropdown sends the filter request with her user ID behind the scenes, so the query hits the database correctly.

This behavior is automatic for lookup columns, you don't need to configure the filter type separately. If you're using the advanced filters feature (Pro), lookup columns will self-configure as dropdown filters in the filter UI.

When Not to Use a Lookup Field?

Lookup fields are powerful but not always the right tool. A few situations where you should consider alternatives:

• The label is already stored in the entry. If your Gravity Forms field is configured to store the label text rather than a key (some setups use this for simple dropdowns), adding a lookup layer is redundant. Check what's actually in your entry data before configuring a lookup.
• You need the raw value for calculations. If another column or a data bar relies on the numeric value of a field for comparisons or sorting, converting it to a lookup display may affect sort order (sorts on resolved label text, not the original number). In this case, consider keeping the original column as-is and adding a second, separate lookup column for display.
• The source data changes frequently. Lookup resolution happens at render time, so it always reflects the current state of the source (current user display names, current post titles). This is usually what you want, but if you need a historical snapshot of what the label was at entry creation time, you're better off storing the label directly in the form entry via a hidden field populated on submission.
• You're on the Free tier. Lookup fields are a Pro feature. On the Free tier, columns display raw stored values. If your use case requires ID resolution, upgrading to Pro is the path forward.

Summary

Lookup fields bridge the gap between how Gravity Forms stores data (efficiently, as IDs and keys) and how people need to read that data (as meaningful labels and names). For any table column that shows IDs, codes, or stored values that mean nothing without context, a lookup field is the right solution. The three-tier fallback system means many fields resolve automatically, and the integration with inline editing and dropdown filters makes the feature consistent across the full read/edit/filter workflow.

If you're building a load-tracking dashboard, a task assignment board, a client portal, or any data table where relational IDs surface in columns, lookup fields will be one of the first Pro features you reach for.

The column mapping you define here is stored as a JSON configuration in the WordPress database. You can export this configuration using the TableCrafter export tool and import it to another table or another site. This is useful when replicating a table layout across multiple pages or when migrating a table to a staging environment for testing before going live.