Image Upload

ProNew

A single-image field for avatars, covers and logos: choose, drop or paste, with type, size and minimum-dimension checks, a preview, Replace and Remove, and an upload progress overlay.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/image-upload

Usage

To crop before saving, open ImageCropper with an object URL of the chosen file, then pass the cropped blob back to this field.

Props

Prop	Type	Default	Description
`value` / `onChange`	`File \| string \| null` / `(File \| null) => void`	-	A new file, or the saved image URL.
`label`, `description`	`string`	-	Visible label and hint.
`shape`	`circle`, `square`, `wide`	`square`
`accept`	`string[]`	PNG, JPEG, WebP, GIF	MIME types.
`maxSize`, `minWidth`, `minHeight`	`number`	none	Checked before `onChange`.
`progress`	`number`	-	0 to 1 shows the overlay and hides Replace and Remove.
`error`	`string`	-	An outside message.

Accessibility

The picture is one button named by the label and described by the hint (types, size, dimensions) and any error; Enter or Space opens the picker. The preview image is decorative (alt="") because the label and the Replace and Remove buttons carry the meaning.
Replace and Remove are separate buttons next to it, not inside it.
A rejected file is explained in a role="alert" line with the actual and the required value; the message is linked to the button with aria-describedby.
Progress is shown as a percentage over the picture and announced as a polite status ("Uploading 40 percent"). The spinner shown while checking pixels stops under reduced motion.

Testing

The component ships with a Testing Library test (image-upload.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/image-upload

Usage

To crop before saving, open ImageCropper with an object URL of the chosen file, then pass the cropped blob back to this field.

Props

Prop	Type	Default	Description
`value` / `onChange`	`File \| string \| null` / `(File \| null) => void`	-	A new file, or the saved image URL.
`label`, `description`	`string`	-	Visible label and hint.
`shape`	`circle`, `square`, `wide`	`square`
`accept`	`string[]`	PNG, JPEG, WebP, GIF	MIME types.
`maxSize`, `minWidth`, `minHeight`	`number`	none	Checked before `onChange`.
`progress`	`number`	-	0 to 1 shows the overlay and hides Replace and Remove.
`error`	`string`	-	An outside message.

Accessibility

The picture is one button named by the label and described by the hint (types, size, dimensions) and any error; Enter or Space opens the picker. The preview image is decorative (alt="") because the label and the Replace and Remove buttons carry the meaning.
Replace and Remove are separate buttons next to it, not inside it.
A rejected file is explained in a role="alert" line with the actual and the required value; the message is linked to the button with aria-describedby.
Progress is shown as a percentage over the picture and announced as a polite status ("Uploading 40 percent"). The spinner shown while checking pixels stops under reduced motion.

Testing

The component ships with a Testing Library test (image-upload.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.