Retool Table Column Tags (Pills): Single & Multiple Tag Setup

If you've been trying to display Retool table column tags (pills) — those rounded, multicolored label badges — inside a table cell, you're not alone. The Tags component works great on its own, but wiring it into a table column stumped a lot of builders before Retool shipped dedicated column types for it. This guide covers exactly how to do it, what to watch out for, and how to handle both single and multiple tags per cell.

Why You Can't Just Drop a Tags Component Into a Table Column

Retool's Table component has its own column type system — it doesn't accept arbitrary components inside cells the way a custom container would. When you first look at the column type dropdown, you'll see options like Text, Number, Link, and Badge, but historically the pill-style Tags component wasn't among them. Builders were left trying to hack it with HTML transforms or custom column renderers, none of which were clean solutions.

The good news: Retool has since shipped two dedicated column types to solve this — Single Tag and Multiple Tags. Here's how to use both.

How to Enable the Single Tag Column Type in Retool

If you want to display one pill-style tag per row in a table column, the Single Tag column type is what you need. Follow these steps:

• Open your Table component in the Retool editor and click on the column you want to change.
• In the right-hand panel, find the Column type dropdown — it likely defaults to Auto.
• Select Single tag from the list.
• Map the column to the data field in your query that contains the tag label string (e.g., status, category).
• Optionally configure tag color rules using the Tag color setting to map specific values to specific colors.

Common gotcha: Some users report that selecting Single tag causes the dropdown to snap back to Auto. If this happens, try a hard browser refresh (Cmd+Shift+R or Ctrl+Shift+R). This was a rollout-phase bug that has since been resolved, but a refresh usually clears it immediately.

How to Display Multiple Tags Per Cell in a Retool Table

The Single Tag column type does exactly what it says — it renders one tag per cell. If your data has multiple values per row (e.g., a user with roles ["admin", "editor"] or a ticket tagged with several labels), you need the Multiple Tags column type instead.

• In the Column type dropdown, select Multiple tags.
• Make sure the underlying data field returns an array of strings, not a comma-separated string. For example: ["design", "backend", "urgent"] will render as three separate pills; "design, backend, urgent" will render as a single malformed pill.
• If your data comes back from a SQL query as a comma-separated string, you can transform it in the query's Transform tab using JavaScript: return data.map(row => ({ ...row, tags: row.tags.split(",").map(t => t.trim()) }))
• Once the column type is set and the data is properly shaped, each array item will render as its own pill inside the cell.

Formatting Your Data Correctly for Tag Columns

The most common reason tag columns look broken — showing a single ugly pill like ["admin","editor"] as raw text — is a data format mismatch. Here's a quick reference:

• Single Tag: expects a plain string, e.g. "active"
• Multiple Tags: expects a JavaScript array of strings, e.g. ["active", "verified"]
• If your database stores tags as a JSON array string (e.g., '["active","verified"]'), parse it in your transform: JSON.parse(row.tags)
• If using PostgreSQL, you can cast array columns directly and Retool will often interpret them correctly, but explicit parsing in the Transform tab is safer and more predictable.

Customizing Tag Colors in Retool Tables

Both column types support color customization. In the column settings panel, look for the Tag color option. You can define a static color or use a mapping object to assign specific colors to specific tag values — useful for status fields like "active" → green, "inactive" → red, "pending" → yellow. This is configured directly in the UI without needing custom code.

When to Use Tags vs. Badge Column Type

Retool also has a Badge column type, which can look similar but behaves differently. Use Badge when you have a single status value and want a dot + label treatment. Use Single Tag or Multiple Tags when you're representing categorical labels, especially when multiple values per row are possible. The visual difference is subtle, but the semantic and functional difference matters for filtering, sorting, and future extensibility of your internal tool.

Summary

To display pill-style tags in a Retool table column: set the column type to Single tag for one tag per row, or Multiple tags for arrays of tags. Make sure your data is a plain string or an array of strings respectively, transform it in the query's Transform tab if needed, and use the color mapping settings to make statuses visually distinct. No HTML hacks required.