shaamilahmed/Htmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote all the docs - more noob friendly now.

Browse Source 
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
Enciphered
2026-05-05 23:55:26 +05:00
parent c1e1f74557
commit b530bb8c97
35 changed files with 2159 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Components/Avatar.md
+39 -48
View File
@@ -1,32 +1,22 @@
# Avatar
A circular user avatar. Shows an image when a `src` URL is provided; falls back to a text/initials span otherwise.
A circular user icon. Shows a profile photo when a URL is provided, or falls back to text (typically initials) on a neutral background.
---
## HTML structure
## Quick example
```
span.relative.flex.{size classes}.shrink-0.overflow-hidden.rounded-full
img[src, alt, class] ← when src is provided
span.flex.items-center... ← fallback when no src
{fallback text}
```csharp
// Initials only
new Avatar(fallback: "JD")
// With a profile photo
new Avatar(fallback: "Jane Doe", src: "/avatars/jane.jpg")
```
---
## CSS mechanics
| Class | Effect |
|---|---|
| `rounded-full overflow-hidden` | Clips content to a circle |
| `aspect-square h-full w-full object-cover` | Image fills the circle without distortion |
| `bg-muted text-muted-foreground` | Neutral background for the initials fallback |
| Size `h-8 w-8` / `h-10 w-10` / `h-14 w-14` / `h-20 w-20` | sm / default / lg / xl |
---
## Constructor signature
## All the options
```csharp
public Avatar(
@@ -35,56 +25,57 @@ public Avatar(
string size = "default")
```
| Parameter | Description |
| Parameter | What it does |
|---|---|
| `fallback` | Text shown when no `src` is given; also used as `alt` text on the image |
| `src` | Optional image URL |
| `size` | `"sm"` / `"default"` / `"lg"` / `"xl"` |
| `fallback` | The text shown when no image is available — typically initials like `"JD"`. Also used as the `alt` attribute on the image for screen readers. |
| `src` | URL of the profile photo. If omitted, the fallback is shown. |
| `size` | How big the circle is: `"sm"` (32px), `"default"` (40px), `"lg"` (56px), `"xl"` (80px) |
---
## Usage examples
## Real-world examples
### Initials avatar
### Initials in different sizes
```csharp
new Avatar(fallback: "JD")
new Avatar(fallback: "JD", size: "lg")
new Avatar(fallback: "SM", size: "sm") // 32×32 — good for compact lists
new Avatar(fallback: "JD", size: "default") // 40×40 — standard nav bar
new Avatar(fallback: "LG", size: "lg") // 56×56 — profile card header
new Avatar(fallback: "XL", size: "xl") // 80×80 — full profile page
```
### Image avatar with fallback
### Profile page header
```csharp
new Avatar(fallback: "Jane Doe", src: "/avatars/jane.jpg", size: "default")
new Avatar(
fallback: user.DisplayName ?? "?",
src: user.AvatarUrl,
size: "xl")
```
### Sizes
The `fallback` is always required — even with a `src` — because it becomes the `alt` text on the `<img>` tag.
```csharp
new Avatar(fallback: "SM", size: "sm") // 32×32
new Avatar(fallback: "DF", size: "default") // 40×40
new Avatar(fallback: "LG", size: "lg") // 56×56
new Avatar(fallback: "XL", size: "xl") // 80×80
```
### Overlapping avatar stack (e.g. "3 team members")
### Inside a user card
Wrap multiple avatars in a flex container with negative spacing:
```csharp
var avatar = new Avatar(fallback: user.Initials, src: user.AvatarUrl, size: "lg");
// In a page's RenderUserCard override:
protected override void RenderUserAvatar(HtmxRenderContext ctx)
=> avatar.Render(ctx.Next());
```html
<div class="flex -space-x-2">
$$Avatar1$$
$$Avatar2$$
$$Avatar3$$
</div>
```
---
## Tips and tricks
## How it works
- Compute initials before constructing the Avatar — the component does not extract them from a full name. See `MainLayout`'s `GetInitials` helper for a reference implementation.
- Always provide `fallback` even when you also provide `src` — it serves as the `alt` attribute for accessibility.
- The Avatar does not handle image load errors. If you need a graceful image fallback on 404, add an `onerror="this.style.display='none'"` attribute by embedding it in the `src` or use `hxAttrs` in a subclassed version.
- For a group of overlapping avatars (avatar stack), wrap several Avatars in a flex container with negative margin: `<div class="flex -space-x-2">`.
The avatar is a `<span>` clipped to a circle with `rounded-full overflow-hidden`. When a `src` is given, an `<img>` fills the circle using `object-cover` so the photo does not stretch. When there is no `src`, a `<span>` with a muted background shows the fallback text centred inside the circle.
The component does not handle broken image URLs. If you need a fallback when an image 404s, add an `onerror` attribute in the surrounding HTML.
The Avatar does not extract initials from full names — do that yourself before constructing it. `"Jane Doe"` → `"JD"` is two lines of C# and is better kept in your own code.
---