Avatar Upload React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Avatar Upload is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import AvatarUpload from @/components/ui/avatar-upload.

import { useState } from "react"
import { AvatarUpload } from "@/components/ui/avatar-upload"

export function ProfilePhoto() {
  const [avatar, setAvatar] = useState<string | null>("/demo/ana-pop.jpg")

  return (
    <AvatarUpload
      name="Anna Price"
      value={avatar}
      onValueChange={setAvatar}
      onUpload={async (blob, { signal, onProgress }) => {
        const body = new FormData()
        body.append("avatar", blob, "avatar.webp")
        onProgress(0.3)
        const response = await fetch("/api/profile/avatar", { method: "POST", body, signal })
        if (!response.ok) throw new Error("The upload failed")
        onProgress(1)
        const { url } = (await response.json()) as { url: string }
        return url
      }}
      onRemove={() => fetch("/api/profile/avatar", { method: "DELETE" })}
      labels={{
        change: "Update photo",
        cropTitle: "Adjust your photo",
        uploaded: "Looking good! Photo updated",
      }}
    />
  )
}

Props

• value
  string | null

  The controlled picture url; null shows the initials. It becomes the url your onUpload resolves, or a local object url when it resolves nothing.

• defaultValuedefault "null"
  string | null

  The uncontrolled starting picture (a url); null shows the initials. The playground is controlled through value instead.

• onValueChange
  (value: string | null) => void

  Fires with the new url after an upload succeeds, with null on remove, and with the old url when a remove is rolled back.

• namedefault ""
  string

  The person's name: initials and a stable color while there is no picture, and part of the button's accessible name (Change photo, Anna Price).

• onUpload
  (blob: Blob, context: { file: File | null; signal: AbortSignal; onProgress: (fraction: number) => void }) => Promise<string | void>

  Gets the cropped square. Call onProgress(0 to 1) to fill the ring (without calls it spins) and resolve the new url. A rejection rolls the picture back and offers Try again. The signal aborts when the component unmounts or a newer upload starts; a result that arrives after the value changed from outside is ignored. Without onUpload the blob becomes a local object url.

• onRemove
  () => (void | Promise<unknown>)

  The Remove action, shown only when set and there is a picture. It runs at once without a confirm (offer undo in a toast); a returned promise shows the spinning ring and rolls back on rejection.

• onError
  (error: Error) => void

  A wrong file type, a file over maxFileSize, a failed export, upload or remove.

• variantdefault "avatar"
  "avatar" | "row" | "dropzone"

  avatar: the picture with a camera badge, the whole avatar is the button. row: the picture with Change photo and Remove buttons and the hint beside it, for settings lists. dropzone: a dashed tile with the avatar inside, for logos and onboarding.

• sizedefault "lg"
  "md" | "lg" | "xl"

  The avatar: 64 / 96 / 128px. The badge and the check scale with it (24 / 32 / 36px, a 44px hit area on touch).

• shapedefault "circle"
  "circle" | "rounded"

  The avatar and the crop frame. circle exports with transparent corners (unless JPEG); rounded suits logos and crops a plain square.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The camera badge, the progress ring, the drag-over tint and the Save button. A failed upload always turns the ring red.

• colordefault ""
  string

  Any CSS color; replaces the tone.

• ringColordefault ""
  string

  The thin ring that separates the badge and the check from the avatar. Set it to the surface behind the avatar (the page background by default).

• labeldefault ""
  ReactNode

  The field label above the control (W2 field anatomy).

• descriptiondefault ""
  ReactNode

  Helper text under the control.

• errordefault ""
  ReactNode

  Replaces the description, sets aria-invalid and marks the dropzone red.

• showHintdefault true
  boolean

  The hint (JPG, PNG or WebP, up to 10 MB) under the buttons in the row look and inside the dropzone.

• requireddefault false
  boolean

  Marks the label with an asterisk and sets aria-required.

• invaliddefault false
  boolean

  Invalid without a message.

• disableddefault false
  boolean

  Dims the control; no menu, no drops.

• readOnlydefault false
  boolean

  Shows the picture without a badge, a menu or drops.

• progress
  number | null

  External progress (0 to 1) for uploads you run yourself: the ring shows at that share, null spins it, undefined hides it. The playground's fake upload drives the ring itself.

• cropdefault true
  boolean

  The crop step. false uploads the largest centered square at once, without the dialog.

• cameradefault true
  boolean

  The Take photo entry: the front camera through the file input on phones (capture="user"), a live camera dialog on desktops with getUserMedia, hidden where neither works.

• acceptdefault "image/jpeg,image/png,image/webp"
  string

  Allowed types for the picker, drops and pastes; other files get labels.wrongType. Safari converts iPhone HEIC photos to JPEG on pick when JPEG is listed; other browsers reject HEIC.

• maxFileSizedefault 10485760
  number

  Bytes of the chosen file (10 MB); bigger files get labels.tooLarge with the limit formatted. 0 means no limit. The export itself is small.

• outputSizedefault 512
  number

  Width and height of the exported square, in px.

• outputTypedefault "image/webp"
  "image/webp" | "image/jpeg" | "image/png"

  The exported format. JPEG has no transparency, so a round crop fills the corners white.

• outputQualitydefault 0.9
  number

  0 to 1, for WebP and JPEG.

• responsivedefault true
  boolean

  The source menu, the crop step and the camera become bottom sheets below 768px.

• localedefault ""
  string

  Formats the size limit in the error (10 MB). Empty uses UIProvider's locale, then the browser's.

• inputNamedefault ""
  string

  Renders a hidden input with this name and the current url, for plain form posts. (name is the person's name here.)

• id
  string

  The trigger's id; the label and the messages point at it.

• cropperProps
  Partial<Omit<ImageCropperProps, "src">>

  Extra props for the crop step's ImageCropper, e.g. { labels } to translate it, { height: 360 } or { flippable: true }.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• labels
  Partial<AvatarUploadLabels>

  Every visible and announced string: change, choose, takePhoto, remove, cropTitle, cameraTitle, save, cancel, uploading, uploaded, removed, failed, removeFailed, tooLarge(max), wrongType, cameraDenied, cameraStarting, shutter, hint, retry, dropTitle, dropTitleTouch, dropHere. Pass only the keys you translate.

• classNames
  Partial<Record<"root" | "trigger" | "avatar" | "badge" | "progress" | "check" | "actions" | "hint" | "message" | "dialog" | "camera" | "field" | "label" | "description" | "error" | "counter", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root (the Field when a label, description or error is set).

Parts

FAQ

Used in

More React input components