first commit
This commit is contained in:
111
docs/ui/react/react-ui/src/components/avatar/avatar.md
Normal file
111
docs/ui/react/react-ui/src/components/avatar/avatar.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# Avatar
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs --> - avatar.variants — `avatarVariants` is the cva confi…
|
||||
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
|
||||
- avatar.variants — `avatarVariants` is the cva confi…
|
||||
|
||||
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
|
||||
|
||||
- avatar.variants — `avatarVariants` is the cva confi…
|
||||
|
||||
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
|
||||
|
||||
- avatar.variants — `avatarVariants` is the cva confi…
|
||||
|
||||
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
|
||||
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
|
||||
|
||||
## Purpose
|
||||
|
||||
`<Avatar>` is the chassis circular image holder built on `@radix-ui/react-avatar`. It ships as a family of three components — `<Avatar>` (root), `<AvatarImage>`, `<AvatarFallback>` — that compose into the conventional shadcn avatar pattern. Per the shadcn skill rule, ALWAYS pair an `<AvatarImage>` with an `<AvatarFallback>` — Radix swaps the fallback in when the image source fails to load OR when no source is supplied. An Avatar without a fallback flashes empty while loading, then disappears silently on a 404 — both are bugs.
|
||||
|
||||
The root `<Avatar>` exposes a `size` axis with four rungs (`sm` / `default` / `lg` / `xl`) using Tailwind's `size-*` shorthand so width and height stay in lockstep, preventing off-by-one ratio bugs that arise when consumers set width and height independently.
|
||||
|
||||
## Features
|
||||
|
||||
- Four sizes via the `size` axis (`sm` / `default` / `lg` / `xl`) using Tailwind `size-*`.
|
||||
- Three composition primitives — `Avatar` (root), `AvatarImage`, `AvatarFallback`.
|
||||
- Radix-managed image-loading state machine — `<AvatarFallback>` swaps in automatically when the image source fails or has not yet loaded.
|
||||
- `aspect-square object-cover` on `<AvatarImage>` so portrait / landscape sources crop centrally rather than distorting.
|
||||
- Forwards refs to the underlying Radix elements on every sub-component.
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```tsx
|
||||
import { Avatar, AvatarFallback, AvatarImage } from "@suaveplan/react-ui";
|
||||
|
||||
export function UserAvatar() {
|
||||
return (
|
||||
<Avatar>
|
||||
<AvatarImage src="/avatar.png" alt="Jane Doe" />
|
||||
<AvatarFallback>JD</AvatarFallback>
|
||||
</Avatar>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```tsx
|
||||
import { Avatar, AvatarFallback, AvatarImage } from "@suaveplan/react-ui";
|
||||
|
||||
interface AvatarStackUser {
|
||||
readonly id: string;
|
||||
readonly name: string;
|
||||
readonly avatarUrl?: string;
|
||||
}
|
||||
|
||||
export function AvatarStack({ users }: { users: AvatarStackUser[] }) {
|
||||
return (
|
||||
<div className="flex -space-x-2">
|
||||
{users.slice(0, 3).map((user) => (
|
||||
<Avatar key={user.id} size="lg" className="border-2 border-background">
|
||||
{user.avatarUrl != null ? (
|
||||
<AvatarImage src={user.avatarUrl} alt={user.name} />
|
||||
) : null}
|
||||
<AvatarFallback>
|
||||
{user.name
|
||||
.split(" ")
|
||||
.slice(0, 2)
|
||||
.map((part) => part[0])
|
||||
.join("")}
|
||||
</AvatarFallback>
|
||||
</Avatar>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `<Avatar>`
|
||||
|
||||
`forwardRef<…, AvatarProps>` — root container backed by `@radix-ui/react-avatar` `Root`.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `size` | `"sm" \| "default" \| "lg" \| "xl"` | `"default"` | Diameter — uses Tailwind `size-*`. |
|
||||
| _Radix props_ | _Radix-typed_ | — | All `AvatarPrimitive.Root` props. |
|
||||
|
||||
### `<AvatarImage>`
|
||||
|
||||
`forwardRef<…, AvatarImageProps>` — image source. Cover-fits inside the circular surface. Radix swaps in `<AvatarFallback>` automatically when the source fails to load.
|
||||
|
||||
### `<AvatarFallback>`
|
||||
|
||||
`forwardRef<…, AvatarFallbackProps>` — fallback surface. Per shadcn skill rule, REQUIRED in every Avatar. Typical contents are user initials (one or two letters) or an icon.
|
||||
|
||||
#### Errors
|
||||
|
||||
The Avatar components do NOT call `useTranslation()` so they do not interact with the i18n provider. The image's `alt` attribute and the fallback content are consumer-provided; consumers wanting translated alt text should pass `t('user.avatar.alt')` at the call site.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- `size-*` is used at the root so width and height change together — the historical bug where consumers passed `w-10 h-12` and produced an ellipse cannot occur with this API.
|
||||
- Radix manages the image-loading state machine: `<AvatarImage>` is hidden until the image loads successfully, and `<AvatarFallback>` is shown until the image is confirmed loaded. Without a fallback, the avatar surface is empty during the load window and after a load failure.
|
||||
- `<AvatarFallback>` accepts an optional `delayMs` prop (forwarded from Radix) — when set, the fallback is suppressed for that many ms so quick image loads don't cause a brief fallback flash.
|
||||
- The chassis does NOT ship an `AvatarGroup` component — that pattern is consumer composition (`<div className="flex -space-x-2">…</div>` over a list of `<Avatar>`s) and shipping it as a discrete primitive forecloses the many layout variations consumers want.
|
||||
- All sub-components forward refs to the underlying Radix elements so consumers can attach event listeners, focus management, or animation controls without wrapping.
|
||||
Reference in New Issue
Block a user