|
| 1 | +--- |
| 2 | +title: "DtAvatar: Visual Refresh Updates" |
| 3 | +description: "DtAvatar has been updated as part of the Dialtone visual refresh. Size prop moves to a numeric scale, group avatars gain full size support, iconSize is removed, and new color, iconOnly, and deactivated props are introduced." |
| 4 | +--- |
| 5 | + |
| 6 | +## TLDR |
| 7 | + |
| 8 | +> [!WARNING] |
| 9 | +> |
| 10 | +> - `clickable` prop **renamed** to `interactive` |
| 11 | +> - `iconSize` prop **removed** — icon size is now computed automatically from `size` |
| 12 | +> - Group avatars no longer forced to `xs` — they now respect the `size` prop |
| 13 | +> - Group count badge capping is size-aware: sizes 100–250 cap at `9+`, sizes 300+ cap at `99+` |
| 14 | +> - Presence indicator only renders for sizes `100` - `500` |
| 15 | +
|
| 16 | +## Size Prop |
| 17 | + |
| 18 | +`DtAvatar`'s `size` prop now uses a numeric 100–900 scale. T-shirt size strings are still accepted but deprecated and will be removed in a future major version. |
| 19 | + |
| 20 | +**Important:** The default changed from the string `'md'` to the number `300`. If you use `DtAvatar` without a `size` prop, no change is needed. If you bind `size` dynamically, ensure your data is now a number. |
| 21 | + |
| 22 | +| Old value | New value | |
| 23 | +| --- | --- | |
| 24 | +| `"xs"` | `100` | |
| 25 | +| `"sm"` | `200` | |
| 26 | +| `"md"` *(previous default)* | `300` *(new default)* | |
| 27 | +| `"lg"` | `500` | |
| 28 | +| `"xl"` | `800` | |
| 29 | + |
| 30 | +Additional sizes with no t-shirt equivalent: `150`, `250`, `400`, `600`, `700`, `900` |
| 31 | + |
| 32 | +### Migration examples |
| 33 | + |
| 34 | +**Static string → static number** |
| 35 | + |
| 36 | +```html |
| 37 | +<!-- Before --> |
| 38 | +<dt-avatar size="lg" /> |
| 39 | + |
| 40 | +<!-- After --> |
| 41 | +<dt-avatar :size="500" /> |
| 42 | +``` |
| 43 | + |
| 44 | +**Conditional size** |
| 45 | + |
| 46 | +```html |
| 47 | +<!-- Before --> |
| 48 | +<dt-avatar :size="isLarge ? 'lg' : 'md'" /> |
| 49 | + |
| 50 | +<!-- After --> |
| 51 | +<dt-avatar :size="isLarge ? 500 : 300" /> |
| 52 | +``` |
| 53 | + |
| 54 | +**Dynamic bound prop** |
| 55 | + |
| 56 | +```html |
| 57 | +<!-- Before: avatarSize was the string 'md' --> |
| 58 | +<dt-avatar :size="avatarSize" /> |
| 59 | + |
| 60 | +<!-- After: avatarSize is now the number 300 --> |
| 61 | +<dt-avatar :size="avatarSize" /> |
| 62 | +``` |
| 63 | + |
| 64 | +## Group Avatars |
| 65 | + |
| 66 | +Group avatars have two breaking changes. |
| 67 | + |
| 68 | +**1. Size is no longer forced to `xs`.** |
| 69 | + |
| 70 | +Previously, setting the `group` prop silently overrode the `size` prop and rendered the avatar at `xs` regardless of what you passed. That override is removed. Group avatars now render at whatever `size` you provide — or the default `300` if none is set. |
| 71 | + |
| 72 | +If your group avatars were relying on the forced-`xs` behavior, you'll need to explicitly set `:size="100"` to preserve the previous appearance. |
| 73 | + |
| 74 | +```html |
| 75 | +<!-- Before: rendered at xs even though size="lg" was set --> |
| 76 | +<dt-avatar full-name="Dialpad" :group="14" size="lg" /> |
| 77 | + |
| 78 | +<!-- After: renders at 500 — set size="100" to match old xs behavior --> |
| 79 | +<dt-avatar full-name="Dialpad" :group="14" :size="100" /> |
| 80 | +``` |
| 81 | + |
| 82 | +**2. Count badge capping is now size-aware.** |
| 83 | + |
| 84 | +Small avatars (sizes 100–250) cap the displayed count at `9+`. Larger avatars (sizes 300+) cap at `99+`. Previously the cap was always `99+` regardless of size. |
| 85 | + |
| 86 | +## `clickable` → `interactive` |
| 87 | + |
| 88 | +The `clickable` prop has been renamed to `interactive` to more accurately describe its effect: the avatar renders as a `<button>`, becomes keyboard-focusable, and participates in the page's tab order. |
| 89 | + |
| 90 | +```html |
| 91 | +<!-- Before --> |
| 92 | +<dt-avatar full-name="Jane Doe" clickable @click="openProfile" /> |
| 93 | + |
| 94 | +<!-- After --> |
| 95 | +<dt-avatar full-name="Jane Doe" interactive @click="openProfile" /> |
| 96 | +``` |
| 97 | + |
| 98 | +The [migration script](/guides/migration/component-props/#migration-script) (`dialtone-migrate-props`) handles this rename automatically. |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +## `iconSize` Removed |
| 103 | + |
| 104 | +The `iconSize` prop has been removed. Icon size is now computed automatically based on the `size` prop and does not need to be specified. |
| 105 | + |
| 106 | +```html |
| 107 | +<!-- Before --> |
| 108 | +<dt-avatar icon="person" icon-size="300" :size="300" /> |
| 109 | + |
| 110 | +<!-- After --> |
| 111 | +<dt-avatar icon="person" :size="300" /> |
| 112 | +``` |
| 113 | + |
| 114 | +## New Props |
| 115 | + |
| 116 | +The following props have been added and are available immediately — no migration required. |
| 117 | + |
| 118 | +| Prop | Type | Description | |
| 119 | +| --- | --- | --- | |
| 120 | +| `family` | Number (1–12) | Color family (hue). 1=Red, 2=Orange, 3=Amber, 4=Yellow-Green, 5=Green, 6=Teal, 7=Cyan, 8=Blue, 9=Indigo, 10=Purple, 11=Magenta, 12=Pink | |
| 121 | +| `variant` | Number (0–9) | Lightness/chroma variant within the family. 0=darkest, 9=lightest | |
| 122 | +| `iconOnly` | Boolean | Renders the avatar with a transparent background, icon only | |
| 123 | +| `deactivated` | Boolean | Renders the avatar in a desaturated/grayed-out state | |
| 124 | + |
| 125 | +### Color prop (legacy) |
| 126 | + |
| 127 | +The `color` prop remains supported for backward compatibility but is now considered legacy. It is converted internally to `family`/`variant` automatically — you do not need to migrate immediately, but we recommend moving to one of the new approaches. |
| 128 | + |
| 129 | +**What the old `color` values meant** |
| 130 | + |
| 131 | +The `color` prop accepted a numeric string in the format `family * 100 + variant * 10`. For example: |
| 132 | + |
| 133 | +- `color="540"` → family `5` (Green), variant `4` |
| 134 | +- `color="1020"` → family `10` (Purple), variant `2` |
| 135 | +- `color="800"` → family `8` (Blue), variant `0` (darkest) |
| 136 | + |
| 137 | +**What to use instead** |
| 138 | + |
| 139 | +For most cases — user avatars where you want a consistent color tied to the person — use **`seed`**. Pass a unique identifier such as a user ID or email address. The same seed always produces the same family and variant, so the color is stable across renders without you needing to store or manage a color code. |
| 140 | + |
| 141 | +```html |
| 142 | +<!-- Before: hardcoded color code --> |
| 143 | +<dt-avatar full-name="Dialpad" color="540" /> |
| 144 | + |
| 145 | +<!-- After: deterministic from user ID --> |
| 146 | +<dt-avatar full-name="Dialpad" seed="user-12345" /> |
| 147 | +``` |
| 148 | + |
| 149 | +If you need explicit control over the exact color — for example, in a branded context or design system showcase — decode your old value and use `family`/`variant` directly: |
| 150 | + |
| 151 | +```html |
| 152 | +<!-- color="540" decoded: family=5, variant=4 --> |
| 153 | +<dt-avatar full-name="Dialpad" :family="5" :variant="4" /> |
| 154 | +``` |
| 155 | + |
| 156 | +## Presence Indicator |
| 157 | + |
| 158 | +The `presence` prop only renders for sizes **100–500**. Sizes 600 and above do not display presence regardless of the `presence` prop value. |
| 159 | + |
| 160 | +## How to Find Usages |
| 161 | + |
| 162 | +No automated migration tool. To find deprecated t-shirt size usages: |
| 163 | + |
| 164 | +```bash |
| 165 | +grep -rn 'size="xs\|size="sm\|size="md\|size="lg\|size="xl' src/ |
| 166 | +``` |
| 167 | + |
| 168 | +To find `iconSize` usages: |
| 169 | + |
| 170 | +```bash |
| 171 | +grep -rn 'icon-size\|iconSize' src/ |
| 172 | +``` |
0 commit comments