Avatar UploadNew

A profile photo or logo with its upload: pick or drop a picture, crop it in a dialog, get a square file back.

$ pnpm dlx shadcn@latest add @dashral/avatar-upload

Profile photo

JPG, PNG or WebP, up to 5 MB. It's saved as a 512 × 512 picture.

Installation

$ pnpm dlx shadcn@latest add @dashral/avatar-upload

Adds the component, the components it builds on, its npm packages and the theme tokens it uses. Or by its full URL: https://dashral.com/r/avatar-upload.json

When to use

Someone's profile photo, or a workspace or company logo, in a settings form: pick or drop a picture, crop it, upload a small square file.

When not to use

Several files, or files that aren't pictures: File Dropzone.
A crop of another shape, such as a 3:1 cover: Image Cropper with cropImage.

Usage

defaultValue is the photo you have; onValueChange gets the cropped 512 px File to upload, or null when it's removed.

example.tsx

1"use client"
2
3import { AvatarUpload } from "@/components/dashral/avatar-upload"
4
5export default function ProfilePhoto() {
6  return (
7    <AvatarUpload
8      label="Profile photo"
9      description="JPG or PNG, up to 5 MB."
10      defaultValue="https://picsum.photos/id/64/400/400"
11      maxSize={5 * 1024 * 1024}
12      onValueChange={(file) => console.log("upload", file)}
13    />
14  )
15}

Using the npm package? Import from @dashral/ui/components/avatar-upload instead, here and in the examples; the rest is the same.

Examples

Workspace logo

shape="square" with initials as the fallback, saved as a 256 px PNG to keep its transparency.

Workspace logo

Shown in the sidebar and on invoices. A square PNG keeps its transparency.

API reference

AvatarUpload

Prop	Type	Default
`value / defaultValue`	`File \| string \| null` The picture now: a URL (from your server, say) or the File cropped last.	`null`
`onValueChange`	`(file: File \| null) => void` The cropped picture, ready to upload, or null when it's removed.	—
`accept`	`string` Like the accept attribute; only pictures are taken.	`"image/*"`
`maxSize`	`number` Largest picture someone can pick, in bytes, before cropping.	—
`shape`	`"circle" \| "square"` A circle for a person, a square for a logo; the file is square either way.	`"circle"`
`fallback`	`ReactNode` In the picture's place when there's none, e.g. initials.	`a person icon`
`outputSize`	`number` Width and height of the file, in pixels.	`512`
`outputType`	`string` "image/png" keeps a logo's transparency; "image/webp" is smaller.	`"image/jpeg"`
`cropTitle / cropDescription`	`ReactNode` The crop dialog's title and the line under it.	—
`name`	`string` Sends the cropped file with a form, as a file input of that name would. It's empty when nothing new was cropped: tell a removal apart with onValueChange.	—
`disabled / required / id`		—
`label`	`ReactNode` Shown above, linked to the control.	—
`description`	`ReactNode` A hint under the control.	—
`error`	`boolean \| ReactNode` true shows the error style; a message also shows under the control.	—
`labelAction`	`ReactNode` At the end of the label's row, e.g. a “Forgot password?” link or the current value.	—
`withAsterisk`	`boolean` Marks the label with an asterisk, e.g. alongside required.	`false`
`classNames`	`{ root, label, description, error, preview, actions }` Classes for each part.	—
`className`	`string` Extra classes, merged with cn() so yours win.	—

Keyboard

Keys	Action
`Tab`	Focus Upload (or Change) photo, then Remove
`Enter`or`Space`	Open the file picker
`In the dialog`	As on Image Cropper; Escape cancels

Accessibility

The buttons say what they do; the preview beside them is for the pointer and for a dropped file, so it's hidden from screen readers.
The whole control is role="group", named by its label and described by its description.
A refused file is said in an alert, with the reason, and the Upload button is described by it.
A picture that can't be opened or cropped says so in the dialog, and Apply waits until the picture has loaded.

Motion

A new picture fades in over the old one and a removed one fades out (--duration-standard), so the preview never blinks empty.

Related blocks

Whole sections built with Avatar Upload or made for the same job, ready to drop in. Free blocks come with their code; Pro blocks come with Dashral Pro.

Workspace brandingPro
The workspace's name, logo, cover and colour, previewed live in the sidebar, the sign-in page, emails and invoices.
Profile settings
A profile form with a photo cropped as it's picked, beside a card that shows how the profile looks to others as you type.

Browse all 65 blocks