Skip to content

Commit 575c569

Browse files
LibenHailuLibenHailu
committed
add avatar-group component documentation
Signed-off-by: Liben Hailu <libenhailu04@gmail.com>
1 parent 5d2623b commit 575c569

6 files changed

Lines changed: 707 additions & 130 deletions

File tree

‎src/sections/Projects/Sistent/components/avatar-group/code.js‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
import React, { useState } from "react";
2+
import { Avatar, AvatarGroup, SistentThemeProvider } from "@sistent/sistent";
3+
import { SistentLayout } from "../../sistent-layout";
4+
import TabButton from "../../../../../reusecore/Button";
5+
import { CodeBlock } from "../button/code-block";
6+
import { useStyledDarkMode } from "../../../../../theme/app/useStyledDarkMode";
7+
8+
import user1 from "../../../../../assets/images/sistent/placeholder/user.webp";
9+
import user2 from "../../../../../assets/images/sistent/placeholder/user.webp";
10+
import user3 from "../../../../../assets/images/sistent/placeholder/user.webp";
11+
import user4 from "../../../../../assets/images/sistent/placeholder/user.webp";
12+
13+
const TABS = ["Overview", "Guidance", "Code"];
14+
15+
const avatarGroupExamples = [
16+
{
17+
title: "Basic AvatarGroup",
18+
description: "Display a horizontal group of avatars with default overlap.",
19+
element: (
20+
<AvatarGroup>
21+
<Avatar src={user1} alt="User 1" />
22+
<Avatar src={user2} alt="User 2" />
23+
<Avatar src={user3} alt="User 3" />
24+
</AvatarGroup>
25+
),
26+
code: `<AvatarGroup>
27+
<Avatar src="/user1.jpg" alt="User 1" />
28+
<Avatar src="/user2.jpg" alt="User 2" />
29+
<Avatar src="/user3.jpg" alt="User 3" />
30+
</AvatarGroup>`,
31+
id: "basic-group",
32+
},
33+
{
34+
title: "Max Avatars",
35+
description: "Limit the number of visible avatars using the `max` prop.",
36+
element: (
37+
<AvatarGroup max={3}>
38+
<Avatar src={user1} alt="User 1" />
39+
<Avatar src={user2} alt="User 2" />
40+
<Avatar src={user3} alt="User 3" />
41+
<Avatar src={user4} alt="User 4" />
42+
</AvatarGroup>
43+
),
44+
code: `<AvatarGroup max={3}>
45+
<Avatar src="/user1.jpg" />
46+
<Avatar src="/user2.jpg" />
47+
<Avatar src="/user3.jpg" />
48+
<Avatar src="/user4.jpg" />
49+
</AvatarGroup>`,
50+
id: "max-group",
51+
},
52+
{
53+
title: "Custom Spacing",
54+
description: "Control the spacing between avatars.",
55+
element: (
56+
<AvatarGroup spacing="medium">
57+
<Avatar src={user1} />
58+
<Avatar src={user2} />
59+
<Avatar src={user3} />
60+
</AvatarGroup>
61+
),
62+
code: `<AvatarGroup spacing="medium">
63+
<Avatar src="/user1.jpg" />
64+
<Avatar src="/user2.jpg" />
65+
<Avatar src="/user3.jpg" />
66+
</AvatarGroup>`,
67+
id: "spacing-group",
68+
},
69+
{
70+
title: "Shape Variants",
71+
description: "Mix avatar shape variants like square and rounded.",
72+
element: (
73+
<AvatarGroup>
74+
<Avatar variant="rounded" src={user1} />
75+
<Avatar variant="square" src={user2} />
76+
<Avatar src={user3} />
77+
</AvatarGroup>
78+
),
79+
code: `<AvatarGroup>
80+
<Avatar variant="rounded" src="/user1.jpg" />
81+
<Avatar variant="square" src="/user2.jpg" />
82+
<Avatar src="/user3.jpg" />
83+
</AvatarGroup>`,
84+
id: "variant-group",
85+
},
86+
{
87+
title: "Total Avatars",
88+
description:
89+
"You can indicate the total number of avatars using the `total` prop, even if not all are rendered.",
90+
element: (
91+
<AvatarGroup total={7}>
92+
<Avatar src={user1} />
93+
<Avatar src={user2} />
94+
<Avatar src={user3} />
95+
</AvatarGroup>
96+
),
97+
code: `<AvatarGroup total={7}>
98+
<Avatar src="/user1.jpg" />
99+
<Avatar src="/user2.jpg" />
100+
<Avatar src="/user3.jpg" />
101+
</AvatarGroup>`,
102+
id: "total-avatars",
103+
},
104+
{
105+
title: "Custom Surplus Renderer",
106+
description:
107+
"Customize the overflow display using the `renderSurplus` prop for more control over surplus appearance.",
108+
element: (
109+
<AvatarGroup
110+
max={2}
111+
renderSurplus={(surplus) => <span>+{surplus.toString()[0]}k</span>}
112+
total={4251}
113+
>
114+
<Avatar src={user1} />
115+
<Avatar src={user2} />
116+
<Avatar src={user3} />
117+
<Avatar src={user4} />
118+
</AvatarGroup>
119+
),
120+
code: `<AvatarGroup
121+
max={2}
122+
renderSurplus={(surplus) => (
123+
<Avatar sx={{ bgcolor: 'secondary.main' }}>{\`+\${surplus} more\`}</Avatar>
124+
)}
125+
>
126+
<Avatar src="/user1.jpg" />
127+
<Avatar src="/user2.jpg" />
128+
<Avatar src="/user3.jpg" />
129+
<Avatar src="/user4.jpg" />
130+
</AvatarGroup>`,
131+
id: "custom-surplus",
132+
},
133+
];
134+
135+
const AvatarGroupComponent = () => {
136+
const { isDark } = useStyledDarkMode();
137+
const [activeTab, setActiveTab] = useState("Overview");
138+
139+
return (
140+
<SistentLayout title="Avatar Group">
141+
<section className="content">
142+
<a id="Identity">
143+
<h2>Avatar Group</h2>
144+
</a>
145+
<p>
146+
Below are practical implementation examples of the
147+
<code>AvatarGroup</code> component, showcasing different
148+
configurations such as max user limit, spacing, variant styling, and
149+
accessibility-friendly usage. These examples are designed to help you
150+
apply <code>AvatarGroup</code> effectively across team or user-related
151+
interfaces.
152+
</p>
153+
154+
<div className="filterBtns">
155+
{TABS.map((tab) => (
156+
<TabButton
157+
key={tab}
158+
title={tab}
159+
className={activeTab === tab ? "active" : ""}
160+
onClick={() => setActiveTab(tab)}
161+
/>
162+
))}
163+
</div>
164+
165+
<p>
166+
The AvatarGroup component helps visually group multiple avatars in a
167+
compact and meaningful layout, often representing users in a shared
168+
context.
169+
</p>
170+
171+
{activeTab === "Code" && (
172+
<div className="code-examples">
173+
<h3>AvatarGroup Implementation Variants</h3>
174+
<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
175+
{avatarGroupExamples.map(
176+
({ title, description, element, code, id }) => (
177+
<section className="showcase" key={id}>
178+
<h4>{title}</h4>
179+
<p>{description}</p>
180+
<div className="items">{element}</div>
181+
<CodeBlock name={id} code={code} />
182+
</section>
183+
),
184+
)}
185+
</SistentThemeProvider>
186+
</div>
187+
)}
188+
189+
{activeTab === "Overview" && (
190+
<div className="overview">
191+
<h3>Usage</h3>
192+
<p>
193+
Use AvatarGroup when you want to display a group of users or
194+
entities visually. It's useful for team indicators,
195+
collaborations, or contributors. You can adjust overlap, limit
196+
display with `max`, or even indicate a total with `total`.
197+
</p>
198+
</div>
199+
)}
200+
201+
{activeTab === "Guidance" && (
202+
<div className="guidance">
203+
<h3>Design Guidance</h3>
204+
<p>
205+
Keep avatar count minimal (ideally &lt; 5) to reduce clutter.
206+
Surplus avatars should indicate remaining count clearly (e.g.
207+
"+3"). Consider consistent shapes, sizes, and padding across your
208+
app.
209+
</p>
210+
<ul>
211+
<li>
212+
Use `max` and `total` for clear grouping when avatars exceed
213+
space.
214+
</li>
215+
<li>
216+
Use `renderSurplus` to match branding or add tooltips/custom UI.
217+
</li>
218+
<li>Maintain consistent alt texts for accessibility.</li>
219+
</ul>
220+
</div>
221+
)}
222+
</section>
223+
</SistentLayout>
224+
);
225+
};
226+
227+
export default AvatarGroupComponent;

0 commit comments

Comments
 (0)