How to Create Custom Badge Labels and Colors in TableCrafter

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

Status badges turn raw text values like "Pending" or "Approved" into color-coded pill labels that make your data tables scannable at a glance. TableCrafter's built-in badge cell type requires zero CSS or custom code, you configure it entirely inside the table builder, and it works on the free tier. This guide walks you through every step, from enabling the badge cell type on a column to fine-tuning background and text colors for each status value. 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]. External database connections via REST APIs reduce WordPress database query load by up to 55% (Kinsta performance analysis, 2024).

What Status Badges Are (and When to Use Them)?

A status badge is a small, rounded pill rendered inside a table cell. Instead of displaying plain text, TableCrafter wraps the cell value in a <span class="gt-badge"> element styled with the exact background and text colors you specify. Values that have no badge mapping fall through to plain text, so you can badge a subset of values without affecting the rest of the column.

Good use cases include order status columns (Pending, In Progress, Shipped, Cancelled), priority levels (Low, Medium, High, Critical), approval workflows (Draft, Under Review, Approved, Rejected), and any field where a quick visual scan matters more than reading every word.

Badge maps are stored per-column in the table configuration. Each entry in the map consists of a value string (exact, case-sensitive), a background hex color, and a text hex color. When TableCrafter renders an AJAX response it calls GT_Badge_Service::render() server-side to produce the badge HTML before the data reaches the browser. On the initial JS-rendered load the applyBadges() method in the frontend bundle does the same pass client-side, so badges appear consistently regardless of which rendering path fires first.

How Does Opening the Table Builder Work?

Navigate to TableCrafter → Tables in your WordPress admin sidebar. If you are adding a badge to an existing table, hover over the table name and click Edit. To start fresh, click Add New at the top of the list.

The table builder opens with a tabbed interface. You will spend most of your time on the Columns tab, where each column from your data source is listed with its configuration options. If you are connecting to Gravity Forms, the most common data source, TableCrafter reads your form fields and maps them as columns automatically once you select a form.

How Do I Enable the Badge Cell Type on a Column?

Locate the column you want to badge in the Columns tab. Each column row has a Cell Type dropdown. Click that dropdown and select Badge. The option also appears alongside Star Rating and the default plain text display.

Once you select Badge, a badge map editor expands below the cell type dropdown. This is where you define each value-to-color pair.

The cell type is saved in the table configuration under column_cell_types keyed by field ID. TableCrafter validates this server-side against an allowlist, only badge and star_rating are accepted; any other value is discarded before saving.

How Do I Configure Your Badge Map?

With the Badge cell type selected, the badge map editor shows a list of value rows. Each row has three inputs:

• Value, the raw text string to match against incoming cell data
• Background color, a hex color picker for the pill background
• Text color, a hex color picker for the label text inside the pill

Click Add Row to add another value. You can add as many badge entries as you have distinct status values. Rows with an empty or invalid hex color are dropped on save, TableCrafter runs GT_Badge_Service::sanitize_map() over the submitted data before persisting it, stripping any entry where either hex field fails WordPress's sanitize_hex_color() validation.

A realistic badge map for a delivery status column might look like this:

Pending      bg: #fbbf24  text: #000000
In Transit   bg: #3b82f6  text: #ffffff
Delivered    bg: #10b981  text: #ffffff
Cancelled    bg: #ef4444  text: #ffffff
On Hold      bg: #6b7280  text: #ffffff

Choose background colors with enough contrast against your text color to remain readable at the badge's small font size (roughly 0.8em). A dark background generally wants white text; a light background generally wants near-black text. TableCrafter uses #e5e7eb (light gray) and #111827 (near-black) as safe fallbacks if your colors fail validation on the server, so your table degrades gracefully rather than breaking.

How Do Saving and Previewing Your Badges Work?

Once you have filled in the badge map, click Save Table at the top of the table builder. TableCrafter posts the configuration to wp-admin/admin-ajax.php with nonce validation, sanitizes the badge map server-side, and stores it in the WordPress options table keyed to your table ID.

To preview, embed the table on any page or post using one of the shortcodes:

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

All three shortcodes point to the same handler and produce identical output. Replace X with the numeric table ID shown in the Tables list. Load the page and you should see badge pills in the configured column. If a cell value is not in your badge map, it renders as plain text, that is intentional.

TableCrafter handles two rendering paths automatically:

• AJAX responses (sort, filter, paginate, auto-refresh), GT_Badge_Service::render() wraps the value server-side before the JSON response leaves PHP. No extra JavaScript work is needed.
• Initial JS render, the badge-cell.js frontend module runs applyBadges() as a post-render pass, walking all td[data-field-id] cells and wrapping matching values. It skips cells that already contain a .gt-badge span, so double-wrapping is not possible.

How Does Combining Badges with Pro Features Work?

Badges compose cleanly with TableCrafter Pro features that are built on top of the same column configuration system.

Pro Inline editing, when a user clicks a badge cell to edit it, TableCrafter renders a plain text input or dropdown with the raw value, not the badge HTML. Saving writes back through GFAPI::update_entry_field(), and the badge re-renders on the next AJAX refresh. The badge is a display layer only; it never interferes with the underlying editable value.

Pro Role-based column permissions, if you restrict a badge column to specific WordPress roles (table-level or column-level), TableCrafter enforces that server-side. Users without the required role never see the column at all, so the badge map is irrelevant to them. The enforcement happens before the badge render step, not after.

Pro Export (CSV / Excel / PDF), exported files receive the raw text value, not the badge HTML. This keeps exports clean and importable. If you need the status label in a specific column in your export, it will appear as plain text like "Pending" or "Delivered" rather than a styled span.

Pro Auto-refresh, when auto-refresh is enabled on a table, TableCrafter re-fetches entries via AJAX on your configured interval. Badge rendering happens server-side in the AJAX handler, so refreshed rows display badges correctly without any additional configuration.

How Does Troubleshooting Common Issues Work?

If badges are not appearing after you save the table, work through these checks in order:

• Cell type not set to Badge, revisit the column in the table builder and confirm the Cell Type dropdown says "Badge", not the default text option.
• Value mismatch, copy an actual cell value from your live table and paste it directly into the badge map value field. A single extra space, different capitalization, or a trailing newline from a Gravity Forms textarea will break the match.
• Invalid hex colors dropped on save, short hex values like #fff are valid (sanitize_hex_color accepts both three- and six-digit hex). Values like rgb(255,255,255), color names like red, or any non-hex format are rejected and that badge entry is silently dropped. Use a full six-digit hex like #ffffff if you are unsure.
• Caching, if you use a page caching plugin (WP Rocket, NitroPack, W3 Total Cache), clear the page cache after saving the table. The badge configuration is embedded in the JS config object on the page; a stale cached page will use old settings.
• Badge map not persisting, open your browser's developer tools, submit the table save, and check the AJAX response. If the response contains an error, check that your user account has the manage_options capability and that WordPress nonces are working correctly (a mismatch here often points to a security plugin or reverse proxy stripping cookies).