@xsolla/xui-avatar 0.99.0 → 0.101.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +251 -32
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,57 +1,276 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Avatar
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A cross-platform React avatar component that displays user images, icons, or text initials. Supports badges for notifications and can be grouped together.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
+
npm install @xsolla/xui-avatar
|
|
9
|
+
# or
|
|
8
10
|
yarn add @xsolla/xui-avatar
|
|
9
11
|
```
|
|
10
12
|
|
|
11
|
-
##
|
|
13
|
+
## Demo
|
|
14
|
+
|
|
15
|
+
### Basic Avatar
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import * as React from 'react';
|
|
19
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
20
|
+
|
|
21
|
+
export default function BasicAvatar() {
|
|
22
|
+
return (
|
|
23
|
+
<div style={{ display: 'flex', gap: 16 }}>
|
|
24
|
+
<Avatar src="https://example.com/user.jpg" />
|
|
25
|
+
<Avatar text="JD" />
|
|
26
|
+
<Avatar /> {/* Default user icon */}
|
|
27
|
+
</div>
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Avatar Sizes
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import * as React from 'react';
|
|
36
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
37
|
+
|
|
38
|
+
export default function AvatarSizes() {
|
|
39
|
+
return (
|
|
40
|
+
<div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
|
|
41
|
+
<Avatar size="xs" text="XS" />
|
|
42
|
+
<Avatar size="sm" text="S" />
|
|
43
|
+
<Avatar size="md" text="M" />
|
|
44
|
+
<Avatar size="lg" text="L" />
|
|
45
|
+
<Avatar size="xl" text="XL" />
|
|
46
|
+
</div>
|
|
47
|
+
);
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Avatar with Badge
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
import * as React from 'react';
|
|
55
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
56
|
+
|
|
57
|
+
export default function AvatarWithBadge() {
|
|
58
|
+
return (
|
|
59
|
+
<div style={{ display: 'flex', gap: 24 }}>
|
|
60
|
+
<Avatar src="https://example.com/user.jpg" badge />
|
|
61
|
+
<Avatar src="https://example.com/user.jpg" badge badgeCount={5} />
|
|
62
|
+
<Avatar src="https://example.com/user.jpg" badge badgeCount={99} badgeTone="alert" />
|
|
63
|
+
</div>
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Square Avatar
|
|
12
69
|
|
|
13
70
|
```tsx
|
|
14
|
-
import
|
|
71
|
+
import * as React from 'react';
|
|
72
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
73
|
+
|
|
74
|
+
export default function SquareAvatar() {
|
|
75
|
+
return (
|
|
76
|
+
<div style={{ display: 'flex', gap: 16 }}>
|
|
77
|
+
<Avatar src="https://example.com/user.jpg" />
|
|
78
|
+
<Avatar src="https://example.com/user.jpg" square />
|
|
79
|
+
</div>
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Anatomy
|
|
15
85
|
|
|
16
|
-
|
|
86
|
+
Import the component and use it directly:
|
|
17
87
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
88
|
+
```jsx
|
|
89
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
90
|
+
|
|
91
|
+
<Avatar
|
|
92
|
+
src="image-url" // Image source URL
|
|
93
|
+
text="AB" // Text/initials when no image
|
|
94
|
+
icon={<CustomIcon />} // Custom icon when no image
|
|
95
|
+
size="md" // Size variant
|
|
96
|
+
square={false} // Square vs circular
|
|
97
|
+
badge={false} // Show notification badge
|
|
98
|
+
badgeCount={5} // Badge count
|
|
99
|
+
badgeTone="brand" // Badge color tone
|
|
100
|
+
stroke={false} // Show border
|
|
101
|
+
backgroundColor="#color" // Custom background
|
|
102
|
+
onClick={handleClick} // Click handler
|
|
24
103
|
/>
|
|
25
104
|
```
|
|
26
105
|
|
|
27
|
-
##
|
|
106
|
+
## Examples
|
|
107
|
+
|
|
108
|
+
### Avatar with Custom Icon
|
|
28
109
|
|
|
29
|
-
|
|
30
|
-
|
|
110
|
+
```tsx
|
|
111
|
+
import * as React from 'react';
|
|
112
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
113
|
+
import { Building2, Briefcase, Star } from '@xsolla/xui-icons-base';
|
|
31
114
|
|
|
32
|
-
|
|
115
|
+
export default function AvatarWithIcon() {
|
|
116
|
+
return (
|
|
117
|
+
<div style={{ display: 'flex', gap: 16 }}>
|
|
118
|
+
<Avatar icon={<Building2 />} backgroundColor="#4A90D9" />
|
|
119
|
+
<Avatar icon={<Briefcase />} backgroundColor="#9B59B6" />
|
|
120
|
+
<Avatar icon={<Star />} backgroundColor="#F39C12" />
|
|
121
|
+
</div>
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Avatar with Stroke
|
|
127
|
+
|
|
128
|
+
```tsx
|
|
129
|
+
import * as React from 'react';
|
|
130
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
131
|
+
|
|
132
|
+
export default function AvatarWithStroke() {
|
|
133
|
+
return (
|
|
134
|
+
<Avatar
|
|
135
|
+
src="https://example.com/user.jpg"
|
|
136
|
+
stroke
|
|
137
|
+
size="lg"
|
|
138
|
+
/>
|
|
139
|
+
);
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Clickable Avatar
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
import * as React from 'react';
|
|
147
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
148
|
+
|
|
149
|
+
export default function ClickableAvatar() {
|
|
150
|
+
return (
|
|
151
|
+
<Avatar
|
|
152
|
+
text="JD"
|
|
153
|
+
size="lg"
|
|
154
|
+
onClick={() => alert('Avatar clicked!')}
|
|
155
|
+
aria-label="View John Doe's profile"
|
|
156
|
+
/>
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Avatar Group
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
import * as React from 'react';
|
|
165
|
+
import { AvatarGroup } from '@xsolla/xui-avatar';
|
|
166
|
+
|
|
167
|
+
export default function AvatarGroupExample() {
|
|
168
|
+
const users = [
|
|
169
|
+
{ src: 'https://example.com/user1.jpg' },
|
|
170
|
+
{ src: 'https://example.com/user2.jpg' },
|
|
171
|
+
{ initials: 'JD' },
|
|
172
|
+
{ initials: 'AB' },
|
|
173
|
+
{ initials: 'CD' },
|
|
174
|
+
{ initials: 'EF' },
|
|
175
|
+
{ initials: 'GH' },
|
|
176
|
+
];
|
|
177
|
+
|
|
178
|
+
return (
|
|
179
|
+
<AvatarGroup
|
|
180
|
+
list={users}
|
|
181
|
+
maxVisible={5}
|
|
182
|
+
size="md"
|
|
183
|
+
/>
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Badge Tones
|
|
189
|
+
|
|
190
|
+
```tsx
|
|
191
|
+
import * as React from 'react';
|
|
192
|
+
import { Avatar } from '@xsolla/xui-avatar';
|
|
193
|
+
|
|
194
|
+
export default function BadgeTones() {
|
|
195
|
+
return (
|
|
196
|
+
<div style={{ display: 'flex', gap: 24 }}>
|
|
197
|
+
<Avatar text="A" badge badgeCount={3} badgeTone="brand" />
|
|
198
|
+
<Avatar text="B" badge badgeCount={3} badgeTone="success" />
|
|
199
|
+
<Avatar text="C" badge badgeCount={3} badgeTone="warning" />
|
|
200
|
+
<Avatar text="D" badge badgeCount={3} badgeTone="alert" />
|
|
201
|
+
</div>
|
|
202
|
+
);
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## API Reference
|
|
33
207
|
|
|
34
208
|
### Avatar
|
|
35
209
|
|
|
210
|
+
An avatar component for displaying user representation.
|
|
211
|
+
|
|
212
|
+
**Avatar Props:**
|
|
213
|
+
|
|
36
214
|
| Prop | Type | Default | Description |
|
|
37
|
-
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
215
|
+
| :--- | :--- | :------ | :---------- |
|
|
216
|
+
| src | `string` | - | Image source URL. |
|
|
217
|
+
| icon | `ReactNode` | - | Icon to display when no image. |
|
|
218
|
+
| text | `string` | - | Text/initials when no image or icon. |
|
|
219
|
+
| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Size of the avatar. |
|
|
220
|
+
| square | `boolean` | `false` | Square with border radius vs circular. |
|
|
221
|
+
| badge | `boolean` | `false` | Show notification badge. |
|
|
222
|
+
| badgeCount | `ReactNode` | - | Badge count or content. |
|
|
223
|
+
| badgeTone | `"primary" \| "secondary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral"` | - | Badge color tone. |
|
|
224
|
+
| stroke | `boolean` | `false` | Show border around avatar. |
|
|
225
|
+
| backgroundColor | `string` | - | Custom background color. |
|
|
226
|
+
| disableHover | `boolean` | `false` | Disable hover effect. |
|
|
227
|
+
| aria-label | `string` | - | Accessible label. |
|
|
228
|
+
| alt | `string` | - | Alt text for image. |
|
|
229
|
+
| onClick | `() => void` | - | Click handler. |
|
|
230
|
+
|
|
231
|
+
---
|
|
48
232
|
|
|
49
233
|
### AvatarGroup
|
|
50
234
|
|
|
235
|
+
A component for displaying multiple avatars with overlap.
|
|
236
|
+
|
|
237
|
+
**AvatarGroup Props:**
|
|
238
|
+
|
|
51
239
|
| Prop | Type | Default | Description |
|
|
52
|
-
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
240
|
+
| :--- | :--- | :------ | :---------- |
|
|
241
|
+
| list | `AvatarGroupItem[]` | - | **Required.** Array of avatar items. |
|
|
242
|
+
| size | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of avatars. |
|
|
243
|
+
| maxVisible | `number` | `6` | Max avatars before "+N" counter. |
|
|
244
|
+
| stroke | `boolean` | `true` | Show borders on avatars. |
|
|
245
|
+
| avatarBackgroundMode | `"mixed" \| ToneString \| Function` | `"mixed"` | Background color mode. |
|
|
246
|
+
| aria-label | `string` | - | Accessible label for the group. |
|
|
247
|
+
|
|
248
|
+
**AvatarGroupItem:**
|
|
249
|
+
|
|
250
|
+
```typescript
|
|
251
|
+
interface AvatarGroupItem {
|
|
252
|
+
src?: string; // Image URL
|
|
253
|
+
initials?: string; // Text initials
|
|
254
|
+
onClick?: () => void; // Click handler
|
|
255
|
+
tooltip?: string; // Tooltip on hover
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## Theming
|
|
260
|
+
|
|
261
|
+
Avatar uses the design system theme for colors:
|
|
262
|
+
|
|
263
|
+
```typescript
|
|
264
|
+
// Colors accessed via theme
|
|
265
|
+
theme.colors.background.secondary // Default avatar background
|
|
266
|
+
theme.colors.content.primary // Text/icon color
|
|
267
|
+
theme.colors.border.primary // Stroke color
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Accessibility
|
|
271
|
+
|
|
272
|
+
- Supports `aria-label` for screen readers
|
|
273
|
+
- `alt` attribute for images
|
|
274
|
+
- Keyboard accessible when clickable (Enter/Space)
|
|
275
|
+
- Focus indicator follows WCAG guidelines
|
|
276
|
+
- Badge count announced to assistive technology
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xsolla/xui-avatar",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.101.0",
|
|
4
4
|
"main": "./web/index.js",
|
|
5
5
|
"module": "./web/index.mjs",
|
|
6
6
|
"types": "./web/index.d.ts",
|
|
@@ -10,11 +10,11 @@
|
|
|
10
10
|
"build:native": "PLATFORM=native tsup"
|
|
11
11
|
},
|
|
12
12
|
"dependencies": {
|
|
13
|
-
"@xsolla/xui-badge": "0.
|
|
14
|
-
"@xsolla/xui-core": "0.
|
|
15
|
-
"@xsolla/xui-icons-base": "0.
|
|
16
|
-
"@xsolla/xui-primitives-core": "0.
|
|
17
|
-
"@xsolla/xui-tooltip": "0.
|
|
13
|
+
"@xsolla/xui-badge": "0.101.0",
|
|
14
|
+
"@xsolla/xui-core": "0.101.0",
|
|
15
|
+
"@xsolla/xui-icons-base": "0.101.0",
|
|
16
|
+
"@xsolla/xui-primitives-core": "0.101.0",
|
|
17
|
+
"@xsolla/xui-tooltip": "0.101.0"
|
|
18
18
|
},
|
|
19
19
|
"peerDependencies": {
|
|
20
20
|
"react": ">=16.8.0",
|