swatch Field Type

type: 'swatch' renders a color value as a small filled square — useful for design token tables, category color coding, and any dataset where a color is part of the record. The field value is used directly as the CSS background-color.

Core Examples

Basic Swatch Table

Design token table with hex value used as both the swatch color and a plain text column.

Swatch	Name	Token	Hex	Usage
	Primary	--color-primary	#6d28d9	Buttons, links, focus rings
	Success	--color-success	#059669	Confirmations, active states
	Warning	--color-warning	#d97706	Alerts, degraded states
	Danger	--color-danger	#dc2626	Errors, destructive actions
	Neutral	--color-neutral	#6b7280	Borders, muted labels

{ key: 'hex', label: 'Swatch', type: 'swatch' },
{ key: 'hex', label: 'Hex', type: 'text' },

Swatch in Grid Mode

Same data in grid mode — each card shows the color swatch, name, and token.

Color:

Name:Primary

Token:--color-primary

Color:

Name:Success

Token:--color-success

Color:

Name:Warning

Token:--color-warning

Color:

Name:Danger

Token:--color-danger

Color:

Name:Neutral

Token:--color-neutral

{ key: 'hex', label: 'Color', type: 'swatch' },
{ key: 'name', label: 'Name', type: 'text' },
{ key: 'token', label: 'Token', type: 'text' },

Formatter — any valid CSS color string

The swatch renderer passes the field value directly to background-color. Any valid CSS color format works: hex, rgb(), hsl(), named colors, CSS variables. Use formatter to normalize or transform the value before it reaches the swatch.

Swatch rendered from the rgb column rather than hex — any CSS color value is accepted.

Swatch (from RGB)	Name	RGB Value	Hex (uppercase)
	Primary	rgb(109, 40, 217)	#6D28D9
	Success	rgb(5, 150, 105)	#059669
	Warning	rgb(217, 119, 6)	#D97706
	Danger	rgb(220, 38, 38)	#DC2626
	Neutral	rgb(107, 114, 128)	#6B7280

// rgb() values work just as well as hex
{ key: 'rgb', label: 'Swatch (from RGB)', type: 'swatch' },

Condition

Usage notes hidden for Neutral — only colors with semantic meaning show usage context.

Swatch	Name	Usage
	Primary	Buttons, links, focus rings
	Success	Confirmations, active states
	Warning	Alerts, degraded states
	Danger	Errors, destructive actions
	Neutral

{
  key: 'usage',
  label: 'Usage',
  type: 'text',
  condition: (entity) => entity.name !== 'Neutral',
}

Field Options Reference

Option	Type	Default	Effect
key	string	required	Entity property whose value is used as the CSS background-color.
label	string	unset	Column header or card label. Also used as the swatch title tooltip.
type	'swatch'	—	Renders a 20×20px colored square with a light border.
formatter	(value, entity) => unknown	unset	Transforms the raw value before it is used as background-color.
condition	(entity) => boolean	unset	Hides the field for rows where the function returns false.
width	CSS length or number	unset	Sets column width in table mode.
align	'left', 'center', 'right'	'left'	Text alignment in table mode.
showLabel	true, false	true when label is set	Shows or hides the label in card/grid layouts.

Caveats

• The swatch is a registered built-in field type, not a switch case in FieldRenderer. This means it goes through the registry path (getWidgemoFieldType) rather than the direct type switch — behavior is identical but the rendering is defined in registries.tsx.
• The swatch dimensions (20×20px) and border are hardcoded in the renderer. They cannot be configured via imageOptions or any other field option today.
• An invalid or empty color value falls back to #ccc (light grey). No error is thrown.
• wrap has no visual effect on a swatch since it renders a block div, not text.
• To display both the swatch and the raw color value, reference the same key twice — once as type: 'swatch' and once as type: 'text'.

Why swatch vs image?

Both render a visual element rather than text. The distinction:

• type: 'swatch' takes a CSS color string and renders a fixed-size colored square. Lightweight, no external request.
• type: 'image' takes a URL and renders a full <img> element with configurable dimensions, shape, and lightbox support.

Use swatch for color metadata. Use image for photos, avatars, or thumbnails.

See Also

• image Field Type
• badge Renderer
• Item Config — item-level shape and layout contract
• Field Config