badge Renderer

renderAs: 'badge' renders a value as a styled pill or inline label. Use colorMap to map values to colors — any value not in the map falls back to defaultColor.

Core Examples

Basic Badge

Status column rendered as colored badges with a colorMap.

Name	Status
Aurora Chen	active
Mateo Silva	pending
Priya Nair	inactive

{
  key: 'status',
  renderAs: 'badge',
  renderAsOptions: {
    colorMap: {
      active:   { background: '#16a34a', text: '#ffffff' },
      pending:  { background: '#d97706', text: '#ffffff' },
      inactive: { background: '#6b7280', text: '#ffffff' },
    },
  },
}

Size Variants

size controls padding and font size. Default is 'md'.

Same status value rendered at sm, md, and lg.

Name	sm	md (default)	lg
Aurora Chen	active	active	active
Mateo Silva	pending	pending	pending
Priya Nair	inactive	inactive	inactive

{ renderAsOptions: { size: 'sm' } }  // compact
{ renderAsOptions: { size: 'md' } }  // default
{ renderAsOptions: { size: 'lg' } }  // larger

Style Variants

'badge' renders a filled pill. 'inline' renders colored text without a background chip.

:::tip Inline style and color For style: 'inline', use textColor in the ColorConfig (not a plain hex string) to set the text color. Plain strings are treated as background colors and auto-contrasted to white — which is invisible on a white page. :::

Badge style (filled pill) vs inline style (colored text). The inline column uses textColor.

Name	badge style	inline style
Aurora Chen	active	active
Mateo Silva	pending	pending
Priya Nair	inactive	inactive

// filled pill — colorMap value can be a plain string or ColorConfig
{ renderAsOptions: { style: 'badge', colorMap: { active: '#16a34a' } } }

// inline — must use textColor so the text is visible
{ renderAsOptions: { style: 'inline', colorMap: { active: { textColor: '#16a34a' } } } }

Icons in Badges

Add an icon name to any ColorConfig entry. iconPosition controls whether the icon appears 'left' (default), 'right', or 'only' (hiding the text label).

Same status column with icon on the left vs the right.

Name	icon left (default)	icon right
Aurora Chen	active	active
Mateo Silva	pending	pending
Priya Nair	inactive	inactive

// icon on the left (default)
colorMap: {
  active:   { background: '#16a34a', text: '#ffffff', icon: 'check-circle', iconPosition: 'left' },
  pending:  { background: '#d97706', text: '#ffffff', icon: 'clock',        iconPosition: 'left' },
  inactive: { background: '#6b7280', text: '#ffffff', icon: 'close',        iconPosition: 'left' },
}

// icon on the right
colorMap: {
  active:   { background: '#16a34a', text: '#ffffff', icon: 'check-circle', iconPosition: 'right' },
  ...
}

Icon-Only Badges

iconPosition: 'only' hides the text label entirely — useful for compact status indicators. Works with both 'badge' and 'inline' styles. Use iconColor to set the icon's stroke color independently of text.

Icon-only in badge style (tinted pill) and inline style (bare icon).

Name	icon only (badge)	icon only (inline)
Aurora Chen
Mateo Silva
Priya Nair

// icon-only badge — tinted background, no label
colorMap: {
  active:   { background: '#dcfce7', iconColor: '#16a34a', icon: 'check-circle', iconPosition: 'only' },
  pending:  { background: '#fef3c7', iconColor: '#d97706', icon: 'clock',        iconPosition: 'only' },
  inactive: { background: '#f3f4f6', iconColor: '#6b7280', icon: 'close',        iconPosition: 'only' },
}

// icon-only inline — bare icon, no background, no label
{
  style: 'inline',
  colorMap: {
    active:   { iconColor: '#16a34a', icon: 'check-circle', iconPosition: 'only' },
    ...
  },
}

Inline Style with Icon and Color

Combine textColor and icon in an inline badge for a compact, no-background status label with a leading icon.

Inline style: colored text and icon side by side, no background chip.

Name	inline + icon
Aurora Chen	active
Mateo Silva	pending
Priya Nair	inactive

{
  style: 'inline',
  colorMap: {
    active:   { textColor: '#16a34a', icon: 'check-circle', iconColor: '#16a34a', iconPosition: 'left' },
    pending:  { textColor: '#d97706', icon: 'clock',        iconColor: '#d97706', iconPosition: 'left' },
    inactive: { textColor: '#6b7280', icon: 'close',        iconColor: '#6b7280', iconPosition: 'left' },
  },
}

Fallback Color

defaultColor applies when the value is not in colorMap. Priya's bronze tier is not mapped — it uses the default grey.

gold and silver are mapped; bronze falls back to defaultColor.

Name	Tier
Aurora Chen	gold
Mateo Silva	silver
Priya Nair	bronze

{
  renderAsOptions: {
    colorMap: {
      gold:   { background: '#f59e0b', text: '#78350f' },
      silver: { background: '#94a3b8', text: '#1e293b' },
    },
    defaultColor: { background: '#e5e7eb', text: '#374151' },
  },
}

Options Reference

Option	Type	Default	Effect
colorMap	Record<string, string | ColorConfig>	{}	Maps field values to colors. String values are used as background color (text auto-contrasted).
defaultColor	string | ColorConfig	'#6c757d'	Fallback color for values not in colorMap.
style	'badge' | 'inline'	'badge'	'badge': filled pill. 'inline': colored text only.
size	'sm' | 'md' | 'lg'	'md'	Controls padding and font size.
className	string	unset	Additional CSS class on the root element.

ColorConfig shape

{
  background?: string;   // pill background color
  text?: string;         // label text color — auto-contrasted against background if omitted
  textColor?: string;    // explicit label text color; takes priority over `text` for inline style
  icon?: string;         // icon name from the Widgemo icon registry
  iconPosition?: 'left' | 'right' | 'only';  // default: 'left'; 'only' hides the text label
  iconColor?: string;    // icon stroke/fill color; falls back to `text` if omitted
  displayText?: string;  // overrides the field value as the visible label text
}

:::note text vs textColor

• text is computed for badge-style contrast: if omitted it is auto-contrasted against background. It also acts as the iconColor fallback.
• textColor overrides the label color for inline style and takes priority over text for the label. Use textColor whenever you need a specific foreground color without influencing icon contrast. :::

Caveats

• An empty or nullish value renders a - placeholder — it does not throw.
• When colorMap maps a value to a plain hex string (active: '#16a34a'), the text color is auto-contrasted for badge backgrounds (typically white). For style: 'inline', this produces white text on a white page — use { textColor: '#16a34a' } instead.
• icon expects a name registered with the Widgemo icon registry. Unrecognized names render nothing silently.
• iconPosition: 'only' hides the label but the field value is still used for colorMap lookup and accessibility semantics.

See Also

• select Field Type — badge is the natural pair for select fields
• Renderer Components Overview
• Field Config