AvatarPicker

Dialog-based avatar selection with circular crop

Overview

AvatarPicker provides a dialog-based avatar upload experience with drag-and-drop, image cropping, and zoom controls. It handles file validation, circular cropping, and uploads to the Files API.

Key Features

Drag-and-drop or click-to-browse file upload
Circular crop with zoom controls (1x-3x)
Displays initials when no avatar is set
Multiple size variants (sm, md, lg, xl, 2xl)
Remove avatar option when image is set

Examples

Interactive Demo

Click the avatar to open the picker dialog. Upload an image and use the crop controls to adjust.

Click to upload an avatar

Size Variants

Available size variants from sm (48px) to 2xl (144px).

lg (default)

2xl

States

Empty state shows initials. With image shows the avatar. Disabled prevents interaction.

Empty (initials)

With image

Disabled

Props Reference

Prop	Type	Default	Description
`value`	`string \| null`	`-`	Current avatar URL (null for no avatar)
`onChange`	`(url: string \| null) => void`	`required`	Callback when avatar changes (URL or null when removed)
`userName`	`string`	`-`	User name for generating fallback initials
`size`	`'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	`'lg'`	Size of the avatar preview button
`disabled`	`boolean`	`false`	Disable picker interactions
`className`	`string`	`-`	Additional className for the container

Usage

import { AvatarPicker } from '@/ui/components';

// Basic usage
const [avatarUrl, setAvatarUrl] = useState<string | null>(null);

<AvatarPicker
  value={avatarUrl}
  onChange={setAvatarUrl}
  userName="John Doe"
/>

// With size variants
<AvatarPicker
  value={avatarUrl}
  onChange={setAvatarUrl}
  userName="Jane Smith"
  size="xl"
/>

// Disabled state
<AvatarPicker
  value={avatarUrl}
  onChange={setAvatarUrl}
  userName="Disabled User"
  disabled
/>