# Icon Component — LLM Reference

`Icon` renders a dynamically generated icon using the Iconify API. It supports color, size, rotation, background, borders, and clickable links while maintaining excellent email client compatibility (including Outlook via VML).

---

## Position in the Document Tree

```
DocumentTree
└── Section
    └── Container
        └── Column
            └── Text
            └── Icon           ← inline or standalone icon
            └── Spacer
            └── Button
```

`Icon` is a leaf node. It can be placed anywhere a child component is accepted.

---

## ComponentNode JSON Structure

```json
{
  "id": "unique-string-id",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:arrow-right",
    "height": "24",
    "width": "24",
    "color": "#000000"
  }
}
```

---

## `IconConfig` — Full Property Reference

| Property              | Type                                      | Required | Description |
|-----------------------|-------------------------------------------|----------|-------------|
| `iconIdentifier`      | `string`                                  | Yes      | Iconify icon name (e.g. `"mdi:home"`, `"logos:react"`) |
| `height`              | `string \| number`                        | Yes      | Icon height in pixels |
| `width`               | `string \| number`                        | No       | Icon width in pixels |
| `rotate`              | `number`                                  | No       | Rotation angle in degrees |
| `rotateOrientation`   | `"cw" \| "ccw"`                           | No       | Rotation direction |
| `color`               | `string`                                  | No       | Icon color (hex recommended) |
| `innerLink`           | `IInnerLink`                              | No       | Makes icon clickable |
| `backgroundColor`     | `string`                                  | No       | Background color of container |
| `padding`             | `string`                                  | No       | Padding around icon |
| `borderRadius`        | `string`                                  | No       | Border radius of container |
| `border`              | `BorderConfig`                            | No       | Border configuration |
| `justifyContent`      | `"start" \| "center" \| "end"`            | No       | Horizontal alignment |

---

## `innerLink` Structure

```json
"innerLink": {
  "type": "url" | "email" | "phone" | "anchor" | "page_top" | "page_bottom" | "none",
  "url"?: string,
  "email"?: string,
  "phone"?: string,
  "anchor"?: string,
  "target"?: "_blank" | "_self"
}
```

---

## How It Works

- Icons are generated at runtime via the Iconify API as PNG images.
- Uses a nested table structure for email compatibility.
- When `backgroundColor` + `borderRadius` are used, VML (`<v:roundrect>`) is injected for Outlook Classic support.
- `display: block`, `fontSize: 0`, and `lineHeight: 0` are used to eliminate unwanted spacing.
- Alignment is handled via the `align` attribute on the outer table.

---

## React Usage

```tsx
import Icon, { IconConfig } from './Icon';

const config: IconConfig = {
  iconIdentifier: "mdi:check-circle",
  height: 32,
  width: 32,
  color: "#22c55e",
  justifyContent: "center"
};

<Icon config={config} />
```

The component is memoized via `arePropsEqual`.

---

## Common Patterns & Examples

### 1. Simple icon

```json
{
  "id": "icon_check",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:check",
    "height": 24,
    "width": 24,
    "color": "#10b981"
  }
}
```

### 2. Clickable icon (linked)

```json
{
  "id": "icon_link",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:arrow-right",
    "height": 20,
    "width": 20,
    "color": "#3b82f6",
    "innerLink": {
      "type": "url",
      "url": "https://example.com",
      "target": "_blank"
    }
  }
}
```

### 3. Icon with background and border radius

```json
{
  "id": "icon_bg",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:star",
    "height": 28,
    "width": 28,
    "color": "#ffffff",
    "backgroundColor": "#eab308",
    "padding": "8px",
    "borderRadius": "9999px"
  }
}
```

### 4. Rotated icon

```json
{
  "id": "icon_rotate",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:refresh",
    "height": 24,
    "width": 24,
    "rotate": 45,
    "color": "#64748b"
  }
}
```

### 5. Right-aligned icon

```json
{
  "id": "icon_align",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:chevron-right",
    "height": 18,
    "width": 18,
    "color": "#94a3b8",
    "justifyContent": "end"
  }
}
```

### 6. Icon with height only (width follows height)

```json
{
  "id": "icon_square",
  "type": "IconComponent",
  "config": {
    "iconIdentifier": "mdi:account",
    "height": 32,
    "color": "#ef4444"
  }
}
```

---

## Data Bindings

`Icon` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the component. `visible` and `propertyMap` are fully supported.

```json
{
  "id": "dynamic-icon",
  "type": "IconComponent",
  "bindings": {
    "visible": "item.hasIcon === true",
    "propertyMap": {
      "config.iconIdentifier": "item.iconName",
      "config.color": "item.iconColor",
      "config.height": "item.iconSize"
    }
  },
  "config": {
    "iconIdentifier": "mdi:check-circle",
    "height": 24,
    "color": "#10b981"
  }
}
```

| Property | Description |
|---|---|
| `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. |
| `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. |

> Bindable properties include `config.iconIdentifier`, `config.color`, `config.backgroundColor`, `config.height`, `config.width`, and any other scalar `IconConfig` field.

---

## Rules & Constraints

- `iconIdentifier` is **required** — without it the component renders nothing.
- `height` is **required** — always specify the icon height explicitly.
- Use full Iconify format: `"{collection}:{icon-name}"` (e.g. `mdi:home`, `logos:figma`, `ion:heart`).
- Width and height must be numbers or pixel strings (e.g. `24` or `"24px"`).
- When `width` is omitted, the icon renders as a square using the `height` value for both dimensions.
- Hex colors (`#rrggbb`) are recommended for best compatibility.
- `borderRadius` + `backgroundColor` together trigger VML for Outlook rounded backgrounds.
- The icon is always rendered with `object-fit: contain`.
- `alt` text is intentionally empty (`""`) as icons are decorative in most email use cases.