Icon Reference

This guide lists all valid icon names available for use in REFRACT PDF documents, including conditional styles, cards, tables, and other components.

Status Icons

Use these icons to indicate status, state, or result conditions.

Information Icons

Use these icons for informational or labeling purposes.

Content Icons

Use these icons for document, file, and content types.

System Icons

Use these icons for organizational, security, and communication elements.

There is no checkbox-checked, checkbox-unchecked, radio-checked or radio-unchecked icon - these are not in the icon registry. Use check for a checked/true state, and text or a blank cell for an unchecked/false state.

Usage Examples

In Conditional Styles

{
  "key": "status",
  "label": "Status",
  "conditionalStyles": [
    {
      "value": "APPROVED",
      "icon": "check",
      "color": "#4CAF50",
      "styleTarget": "icon"
    },
    {
      "value": "PENDING",
      "icon": "clock",
      "color": "#FF9800",
      "styleTarget": "icon"
    },
    {
      "value": "REJECTED",
      "icon": "x",
      "color": "#D32F2F",
      "styleTarget": "icon"
    },
    {
      "value": "WARNING",
      "icon": "circlealert",
      "color": "#FF9800",
      "styleTarget": "icon"
    }
  ]
}

In Cards

{
  "type": "card",
  "props": {
    "title": "Order Status",
    "fields": [
      {
        "key": "orderStatus",
        "label": "Status",
        "value": "{{orderStatus}}",
        "conditionalStyles": [
          {
            "value": "COMPLETED",
            "icon": "check",
            "color": "#4CAF50"
          },
          {
            "value": "SHIPPED",
            "icon": "package",
            "color": "#2196F3"
          }
        ]
      }
    ]
  }
}

In Tables

Column-level conditionalStyles only take effect when the column is declared through props.columnManifest.columns[] - see Conditional Styles and Table.

{
  "type": "table",
  "props": {
    "title": "Security Audit",
    "dataPath": "auditItems",
    "columnManifest": {
      "columns": [
        { "key": "auditItem", "label": "Item", "displayOrder": 0 },
        {
          "key": "result",
          "label": "Result",
          "displayOrder": 1,
          "conditionalStyles": [
            {
              "value": "PASSED",
              "icon": "check",
              "color": "#4CAF50",
              "displayMode": "icon"
            },
            {
              "value": "FAILED",
              "icon": "x",
              "color": "#D32F2F",
              "displayMode": "icon"
            },
            {
              "value": "NOT_TESTED",
              "icon": "info",
              "color": "#999999",
              "displayMode": "icon"
            }
          ]
        }
      ]
    }
  }
}

Migration Guide

The renderer resolves an icon key in two steps: first as an exact, case-sensitive match against the registry names above; if that fails, against a small legacy alias table kept for templates saved before the registry was renamed. These are the only legacy aliases that exist - any other capitalized or old-style name not listed here does not resolve, and the icon is silently dropped rather than raising an error.

FileText is also in this alias table, but it maps to file-text, which is not itself a registry key - so FileText does not resolve to anything either. Use file directly instead.

Names like AlertCircle, TrendingUp, TrendingDown, Loader, Activity, Edit, Trash, Download, Upload, Copy, Server, Database, Wifi, WifiOff, HardDrive, MessageSquare, Mail and Bell are not registry keys and not legacy aliases - they do not resolve. Use the direct registry names from the tables above instead (for example, circlealert for an alert icon, email for a mail icon, building for a server/organization icon).

Icon Placement Best Practices

With displayMode

• displayMode: "icon" - Icon only (best for status indicators)
• displayMode: "label" - Text only (no icon)
• displayMode: "iconAndLabel" - Icon plus text (default, best for descriptions)

With styleTarget

• styleTarget: "icon" - Apply colors to icon only
• styleTarget: "text" - Apply colors to text only
• styleTarget: "cell" - Apply colors to entire cell background

Examples

Status icon with green color:

{
  "value": "ACTIVE",
  "icon": "check",
  "color": "#4CAF50",
  "displayMode": "icon",
  "styleTarget": "icon"
}

Alert with red background:

{
  "value": "ERROR",
  "icon": "circlealert",
  "color": "#FFFFFF",
  "bgColor": "#D32F2F",
  "displayMode": "iconAndLabel",
  "styleTarget": "cell"
}

Unicode Characters for Text-Based Styling

As an alternative to SVG icons, plain Unicode characters can be used directly in text fields, feature lists, and CTA labels - but only for characters the embedded PDF body font (Roboto Regular) actually has glyphs for. A character the font lacks does not render at all in the PDF, even though it displays fine in a code editor or a browser preview (which silently falls back to a different font). The tables below were checked directly against the embedded font's character map and list only what actually renders, plus the specific characters template authors commonly reach for that do not.

Navigation & Directional (CTAs)

For a right-pointing arrow in a CTA, use » or plain text ("Get Started") rather than → or ➔ - neither renders.

Example in Bento Card CTA:

{
  "cta": {
    "primary": "Get Started",
    "secondary": "Learn More »"
  }
}

Status & Validation (Reports)

None of the marks template authors actually want for pass/fail/warning states (check mark, heavy check, a proper cross, warning triangle, info) render in the embedded font. Use the SVG icon registry instead - check, x, warning and info are real icons that render correctly, either directly on a card/table/bento_card icon prop or through conditionalStyles.

Example: conditional icon instead of a Unicode character

{
  "key": "validationStatus",
  "label": "Status",
  "conditionalStyles": [
    { "value": "PASS", "icon": "check", "color": "#4CAF50" },
    { "value": "FAIL", "icon": "x", "color": "#D32F2F" }
  ]
}

Example in Feature List:

"features": [
  { "label": "Full encryption" },
  { "label": "99.9% uptime" },
  { "label": "No legacy support", "icon": "x" }
]

List Bullets (Bento Features)

Example in Bento Card Features:

"features": [
  { "label": "Unlimited projects" },
  { "label": "50 GB storage" },
  { "label": "Optional add-ons available" },
  { "label": "Premium support tier" }
]

features[].label does not need a leading bullet character - each feature already renders as its own row with a check icon by default (see Bento Card).

Financial & Metrics (Pricing/Invoices)

All three separator/metric characters here render correctly. The one common addition to avoid is an up-arrow (↑) for a trend indicator - it does not render; use the word "up" or a plus sign instead.

Example in Pricing Card:

{
  "type": "bento_card",
  "props": {
    "title": "Professional",
    "heroSection": {
      "value": "$149",
      "period": "· per month",
      "description": "billed annually"
    }
  }
}

Example in KPI Summary:

{
  "features": [
    { "label": "Performance", "value": "+22% ∆" },
    { "label": "Compression", "value": "≈ 85%" },
    { "label": "File size", "value": "250 KB · avg" }
  ]
}

Combining Unicode with Conditional Styles

conditionalStyles[].label is not a real property - conditional style rules match against value and apply icon/color/bgColor; they do not carry a separate display label. To combine a status word with an icon, keep the cell's own text as the label and let conditionalStyles add the icon:

{
  "key": "auditResult",
  "conditionalStyles": [
    { "value": "PASSED",  "icon": "check",   "color": "#4CAF50" },
    { "value": "FAILED",  "icon": "x",       "color": "#D32F2F" },
    { "value": "WARNING", "icon": "warning", "color": "#FF9800" }
  ]
}

Troubleshooting

Icon Not Displaying

Problem: Icon does not appear even though the name is specified

Solutions:

1. Wrong icon name - Check icon name against the valid list above
2. Case sensitivity - Icon names are lowercase (e.g., check, not Check), except for the legacy aliases in the Migration Guide, which are exact-case PascalCase
3. Typo - Verify spelling matches exactly (e.g., circlealert, not circlealerts)

Icon Color Not Applying

Problem: Icon appears but with wrong color

Solutions:

1. Check styleTarget - Ensure styleTarget is set correctly (use "icon" to color just the icon)
2. Verify color value - Use valid hex colors (e.g., "#4CAF50") or theme tokens (e.g., "theme.success")
3. Theme token - If using theme tokens, ensure the token exists in your configuration

Icon and Text Misaligned

Problem: Icon and text do not align properly

Solutions:

1. Try styleTarget: "icon" - This often fixes alignment issues
2. Adjust displayMode - Use "icon" only if text is not needed
3. Check cell width - Narrow cells may squeeze icon and text together

Performance Tips

• Use simple icons (check, x, info) for better rendering performance
• Prefer displayMode: "icon" when space is limited
• Icons automatically scale with text size, no need to specify separate sizes