Avatar Upload

A profile photo field with a real cropper. Drop an image on the avatar or browse, then frame it in a round mask: drag or arrow keys to move, slider, wheel or +/− to zoom, quarter-turn rotate, a thirds grid while dragging. Saves a square JPEG from a canvas, checks type and size up front, Adjust reframes the original rather than the crop, and Remove falls back to initials.

Tags: avatar upload crop image profile photo settings drag-and-drop
Dependencies: lucide-react(npm, opens in a new tab)

Props

Other props pass through to the root element.

value
string | null
The current photo URL (controlled). null means no photo.
defaultValue
string | null
Default null
onChange
(file: Blob | null, url: string | null) => void
Called with the cropped image and an object URL for it, or with nulls when the photo is removed.
name
string
Used for the initials shown when there's no photo.
maxSize
number
Default 5 * 1024 * 1024
Largest accepted file, in bytes. Defaults to 5 MB.
outputSize
number
Default 512
Width and height of the exported image, in px.
defaultEditing
boolean
Open the cropper on the current photo at mount.
label
React.ReactNode
Default "Profile photo"
description
React.ReactNode
Default "JPG, PNG or WebP, up to 5 MB."

Prop	Type	Default	Description
value	string \| null	–	The current photo URL (controlled). `null` means no photo.
defaultValue	string \| null	null
onChange	(file: Blob \| null, url: string \| null) => void	–	Called with the cropped image and an object URL for it, or with nulls when the photo is removed.
name	string	–	Used for the initials shown when there's no photo.
maxSize	number	5 * 1024 * 1024	Largest accepted file, in bytes. Defaults to 5 MB.
outputSize	number	512	Width and height of the exported image, in px.
defaultEditing	boolean	–	Open the cropper on the current photo at mount.
label	React.ReactNode	"Profile photo"
description	React.ReactNode	"JPG, PNG or WebP, up to 5 MB."