Conditional Styles & Advanced Formatting

Guide to the conditional styling system and advanced formatting options available for cards, tables, hierarchical tables, and note blocks.

This guide covers the conditional styling system and advanced formatting options available for cards, tables, hierarchical tables, and note blocks.

Overview

Conditional styles allow you to apply dynamic formatting (colors, icons, and backgrounds) based on field values. Combined with advanced properties like referenceField, styleTarget, and hidden, you can create sophisticated, data-driven visualizations.

Core Concepts

Conditional Styles Structure

All conditional styles follow this interface:

{
  "conditionalStyles": [
    {
      "value": "FAILED",
      "icon": "AlertCircle",
      "color": "#D32F2F",
      "bgColor": "#FFEBEE",
      "displayMode": "iconAndLabel",
      "styleTarget": "cell",
      "referenceField": null
    }
  ]
}

Available Properties

Property	Type	Default	Description
`value`	string	-	The value to match (case-insensitive). Use `"default"` for fallback styling
`icon`	string	-	Icon name from icon registry (for example, "check", "circlealert")
`color`	string	-	Text or icon color (hex or theme token like "theme.error")
`bgColor`	string	-	Background color (hex or theme token)
`displayMode`	'icon' \| 'label' \| 'iconAndLabel'	'iconAndLabel'	Which elements to display
`styleTarget`	'cell' \| 'icon' \| 'text'	'cell'	Where to apply colors
`referenceField`	string	-	Look up value from different field for matching
`hidden`	boolean	-	Hide column or field from display (on columns only)

Feature 1: styleTarget - Fine-Grained Styling Control

Control exactly which elements receive styling colors.

Three Options

`"styleTarget": "cell"` (DEFAULT)

Applies all styling to the entire cell:

Icon gets the color and background
Text gets the color
Cell background gets bgColor

{
  "value": "SUCCESS",
  "icon": "check",
  "color": "#FFFFFF",
  "bgColor": "#4CAF50",
  "styleTarget": "cell"
}

Result: Icon and text both green on green background

`"styleTarget": "icon"`

Applies styling only to the icon:

Icon gets the color and background
Text remains default color
Cell background stays default

{
  "value": "SUCCESS",
  "icon": "check",
  "color": "#4CAF50",
  "bgColor": "#E8F5E9",
  "styleTarget": "icon"
}

Result: Green checkmark icon on light green background, text stays black

`"styleTarget": "text"`

Applies styling only to the text:

Text gets the color
Icon remains default color
Cell background stays default

{
  "value": "PENDING",
  "icon": "Clock",
  "color": "#FF9800",
  "styleTarget": "text"
}

Result: Orange text with gray icon, no cell background

Visual Comparison

styleTarget: "cell"        styleTarget: "icon"       styleTarget: "text"
┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
│ 🟢 SUCCESS          │   │ 🟢 SUCCESS          │   │ ● SUCCESS           │
│ (green bg, white)   │   │ (light green bg)    │   │ (orange text)       │
└─────────────────────┘   └─────────────────────┘   └─────────────────────┘

Feature 2: referenceField - Cross-Column Styling

Apply styling to one column based on another column's value.

Use Case

You have a Status column with values like "FAILED", "SUCCESS", "PENDING", but you want to display Message text with icons styled based on the Status value, not the Message content.

Configuration

{
  "key": "message",
  "label": "Message",
  "conditionalStyles": [
    {
      "value": "FAILED",
      "icon": "circlealert",
      "color": "#D32F2F",
      "bgColor": "#FFEBEE",
      "referenceField": "status",
      "displayMode": "iconAndLabel"
    },
    {
      "value": "SUCCESS",
      "icon": "check",
      "color": "#4CAF50",
      "bgColor": "#E8F5E9",
      "referenceField": "status"
    },
    {
      "value": "PENDING",
      "icon": "clock",
      "color": "#FF9800",
      "referenceField": "status"
    }
  ]
}

How It Works

Renderer finds the Message field's value
Sees referenceField: "status"
Instead of matching Message value, looks up Status field value
Matches Status value against conditionalStyles rules
Applies matched styling to Message field

Data Example

{
  "status": "FAILED",
  "message": "DATABASE CONNECTION FAILED"
}

Result: Message displays with red icon, red text, and light red background (based on status="FAILED", not message content)

Feature 3: hidden - Hide Columns While Keeping as Reference Source

Hide columns from display but keep their values available for referenceField matching.

Configuration

{
  "key": "status",
  "label": "Status",
  "hidden": true,
  "conditionalStyles": [...]
}

Why Use This?

Reduces visual clutter: Don't show status column if you're using it for cross-column styling
Reference still works: Other columns can still reference hidden columns via referenceField
Data preserved: Hidden columns' data stays in row data for logic

Complete Example

Tables with System, Message, and Status columns:

{
  "columns": [
    {
      "key": "system",
      "label": "System"
    },
    {
      "key": "message",
      "label": "Message",
      "conditionalStyles": [
        {
          "value": "FAILED",
          "icon": "AlertCircle",
          "color": "#D32F2F",
          "styleTarget": "icon",
          "referenceField": "status"
        }
      ]
    },
    {
      "key": "status",
      "label": "Status",
      "hidden": true
    }
  ]
}

Display Result:

System column: Visible
Message column: Visible with styled icons based on Status
Status column: Hidden (not shown to user)

Cards

Cards support the same conditional styling system as tables.

Card Field Example

{
  "type": "card",
  "title": "License Status",
  "fields": [
    {
      "key": "licenseStatus",
      "label": "Status",
      "variant": "success",
      "conditionalStyles": [
        {
          "value": "EXPIRED",
          "icon": "AlertCircle",
          "color": "#D32F2F",
          "styleTarget": "icon"
        },
        {
          "value": "ACTIVE",
          "icon": "check",
          "color": "#4CAF50",
          "styleTarget": "icon"
        }
      ]
    }
  ]
}

Supported Variants

default, info, success, warning, danger
Apply theme-based colors as fallback when no conditional style matches

innerBorderStyle with Conditional Styles

When using innerBorderStyle: "full", cards automatically add padding to prevent text from touching borders. This works seamlessly with conditional styling.

{
  "type": "card",
  "innerBorderStyle": "full",
  "fields": [
    {
      "key": "status",
      "label": "Status",
      "conditionalStyles": [
        {
          "value": "FAILED",
          "color": "#D32F2F",
          "styleTarget": "text"
        }
      ]
    }
  ]
}

Tables

Tables are the primary use case for conditional styling, supporting all features.

Basic Table with Conditional Styles

{
  "type": "table",
  "title": "Systems Status",
  "columns": [
    {
      "key": "system",
      "label": "System",
      "width": "30%"
    },
    {
      "key": "message",
      "label": "Message",
      "width": "50%",
      "conditionalStyles": [
        {
          "value": "FAILED",
          "icon": "circlealert",
          "color": "#D32F2F",
          "bgColor": "#FFEBEE",
          "styleTarget": "cell",
          "referenceField": "status"
        },
        {
          "value": "SUCCESS",
          "icon": "check",
          "color": "#4CAF50",
          "bgColor": "#E8F5E9",
          "styleTarget": "cell",
          "referenceField": "status"
        }
      ]
    },
    {
      "key": "status",
      "label": "Status",
      "hidden": true
    }
  ]
}

Advanced: displayMode + styleTarget

Combine displayMode with styleTarget for complete control:

{
  "key": "result",
  "label": "Result",
  "conditionalStyles": [
    {
      "value": "COMPLETED",
      "icon": "check",
      "color": "#4CAF50",
      "displayMode": "icon",
      "styleTarget": "icon"
    },
    {
      "value": "PENDING",
      "icon": "clock",
      "color": "#FF9800",
      "displayMode": "iconAndLabel",
      "styleTarget": "text"
    },
    {
      "value": "FAILED",
      "icon": "AlertCircle",
      "color": "#D32F2F",
      "bgColor": "#FFEBEE",
      "displayMode": "iconAndLabel",
      "styleTarget": "cell"
    }
  ]
}

Behavior:

COMPLETED: Shows icon only (green)
PENDING: Shows icon plus text (text in orange, icon gray)
FAILED: Shows icon plus text (white on red background)

Default Styling

Use "value": "default" as fallback for unmatched values:

{
  "conditionalStyles": [
    {
      "value": "PRIORITY",
      "icon": "warning",
      "color": "#FF9800"
    },
    {
      "value": "default",
      "icon": "Minus",
      "color": "#999999"
    }
  ]
}

Hierarchical Tables

Hierarchical tables fully support conditional styles with the same features as standard tables.

Example: Multi-Level Data

{
  "type": "hierarchicalTable",
  "title": "Department Performance",
  "parentColumn": "department",
  "columns": [
    {
      "key": "department",
      "label": "Department"
    },
    {
      "key": "status",
      "label": "Status",
      "conditionalStyles": [
        {
          "value": "ON_TRACK",
          "icon": "status",
          "color": "#4CAF50",
          "styleTarget": "icon"
        },
        {
          "value": "AT_RISK",
          "icon": "circlealert",
          "color": "#FF9800",
          "styleTarget": "icon"
        },
        {
          "value": "OFF_TRACK",
          "icon": "status",
          "color": "#D32F2F",
          "styleTarget": "icon"
        }
      ]
    },
    {
      "key": "healthScore",
      "label": "Health",
      "hidden": true
    }
  ]
}

Cross-Column in Hierarchical Tables

The same referenceField pattern works in hierarchical tables:

{
  "key": "actionItems",
  "label": "Action Items",
  "conditionalStyles": [
    {
      "value": "OVERDUE",
      "icon": "circlealert",
      "color": "#D32F2F",
      "bgColor": "#FFEBEE",
      "referenceField": "status",
      "styleTarget": "cell"
    }
  ]
}

Note Block

Note blocks are specialized content blocks for displaying highlighted information, warnings, or important messages.

Component Type

{
  "type": "note_block",
  "variant": "info",
  "title": "Important",
  "description": "This is additional information"
}

Available Variants

Variant	Use Case	Icon	Default Color
`info`	General information	InfoCircle	Blue (#2196F3)
`success`	Positive or completed action	check	Green (#4CAF50)
`warning`	Caution or attention needed	AlertTriangle	Orange (#FF9800)
`danger`	Error or critical issue	AlertCircle	Red (#D32F2F)

Basic Example

{
  "type": "note_block",
  "variant": "info",
  "title": "System Update",
  "description": "The system will be updated on 2024-04-20 from 2:00 PM to 4:00 PM EST"
}

Warning Note Block

{
  "type": "note_block",
  "variant": "warning",
  "title": "License Expiring Soon",
  "description": "Your license will expire on 2024-12-31. Please renew before expiration to avoid service interruption."
}

Error or Danger Note Block

{
  "type": "note_block",
  "variant": "danger",
  "title": "Connection Failed",
  "description": "Unable to connect to the database. Please check your connection string and try again."
}

Success Note Block

{
  "type": "note_block",
  "variant": "success",
  "title": "Import Complete",
  "description": "Successfully imported 1,250 records from the CSV file"
}

With showVariantLabel

Display the variant type as a prefix to the title:

{
  "type": "note_block",
  "variant": "warning",
  "title": "License Expiring",
  "description": "Your license expires in 7 days",
  "showVariantLabel": true
}

Output: "WARNING: License Expiring"

Styling Properties

Note blocks support theme-based styling:

{
  "type": "note_block",
  "variant": "info",
  "title": "Custom Title",
  "description": "Custom description",
  "bgColor": "theme.info.light",
  "borderColor": "theme.info.main",
  "textColor": "theme.info.dark"
}

Combining Note Blocks in Layout

Note blocks work with section layouts:

{
  "type": "section",
  "title": "System Status Report",
  "children": [
    {
      "type": "note_block",
      "variant": "info",
      "title": "Report Generated",
      "description": "Generated on 2024-04-16 at 14:30 UTC"
    },
    {
      "type": "table",
      "title": "System Details",
      "columns": [...]
    },
    {
      "type": "note_block",
      "variant": "warning",
      "title": "Attention Required",
      "description": "Review the failed systems above"
    }
  ]
}

Responsive: 50/50 Grid with Note Block

{
  "type": "gridTable",
  "rows": [
    {
      "columns": [
        {
          "width": "50%",
          "content": [
            {
              "type": "table",
              "title": "Active Systems",
              "columns": [...]
            }
          ]
        },
        {
          "width": "50%",
          "content": [
            {
              "type": "note_block",
              "variant": "success",
              "title": "All Systems Operational",
              "description": "18 systems running normally with no errors or warnings"
            }
          ]
        }
      ]
    }
  ]
}

Complete Real-World Example

Document with all features combined:

{
  "sections": [
    {
      "type": "section",
      "title": "Deployment Status",
      "children": [
        {
          "type": "note_block",
          "variant": "info",
          "title": "Deployment Report",
          "description": "Generated 2024-04-16 | Production Environment",
          "showVariantLabel": false
        },
        {
          "type": "table",
          "title": "Systems Status",
          "columns": [
            {
              "key": "system",
              "label": "System",
              "width": "25%"
            },
            {
              "key": "message",
              "label": "Status Message",
              "width": "50%",
              "conditionalStyles": [
                {
                  "value": "FAILED",
                  "icon": "AlertCircle",
                  "color": "#D32F2F",
                  "bgColor": "#FFEBEE",
                  "displayMode": "iconAndLabel",
                  "styleTarget": "cell",
                  "referenceField": "status"
                },
                {
                  "value": "SUCCESS",
                  "icon": "CheckCircle",
                  "color": "#4CAF50",
                  "bgColor": "#E8F5E9",
                  "displayMode": "iconAndLabel",
                  "styleTarget": "cell",
                  "referenceField": "status"
                },
                {
                  "value": "PENDING",
                  "icon": "Clock",
                  "color": "#FF9800",
                  "displayMode": "iconAndLabel",
                  "styleTarget": "text",
                  "referenceField": "status"
                }
              ]
            },
            {
              "key": "status",
              "label": "Status",
              "hidden": true
            }
          ]
        }
      ]
    },
    {
      "type": "card",
      "title": "Summary",
      "fields": [
        {
          "key": "totalSystems",
          "label": "Total Systems"
        },
        {
          "key": "deploymentStatus",
          "label": "Overall Status",
          "conditionalStyles": [
            {
              "value": "COMPLETED",
              "icon": "CheckCircle",
              "color": "#4CAF50",
              "styleTarget": "icon"
            },
            {
              "value": "IN_PROGRESS",
              "icon": "Loader",
              "color": "#FF9800",
              "styleTarget": "icon"
            }
          ]
        }
      ]
    }
  ]
}

Migration Notes

From Previous Versions

If you're upgrading from a version without styleTarget, referenceField, or hidden:

Existing conditionalStyles still work - styleTarget defaults to "cell" maintaining backward compatibility
No referenceField - All conditionals match against current field value (existing behavior)
All columns visible - hidden property defaults to false

Adding New Features

// Old (still works):
{
  "value": "FAILED",
  "color": "#D32F2F",
  "bgColor": "#FFEBEE"
}

// New (more control):
{
  "value": "FAILED",
  "color": "#D32F2F",
  "bgColor": "#FFEBEE",
  "styleTarget": "icon",
  "referenceField": "status"
}

Troubleshooting

Conditional Style Not Matching

Check the value: Matching is case-insensitive, but spelling must match exactly
Verify referenceField: If using referenceField, ensure the referenced column key exists
Check data format: Ensure your data has the expected values
Try "default": Add a "value": "default" rule to catch unmatched cases

Hidden Columns Not Referenced

Ensure referenceField points to the correct column key
Hidden columns must exist in the data, even if not visible

Icon Alignment Issues

Icons are SVG-based and align to text baseline
Use styleTarget: "icon" if background looks misaligned
Icons scale proportionally with text size

Icon Reference

Popular icons for conditional styles:

Status Icons: check, circlealert, warning, clock, status
Information Icons: info, tag, star
Content Icons: file-text, file, package, list, image, barcode, qr
System Icons: building, shield, phone, email, link

For the complete icon registry, see Icon Reference.

Conditional Styles & Advanced Formatting

On this page