# `PhiaUi.Components.AvatarUpload`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/inputs/avatar_upload.ex#L1)

Circular or square profile photo uploader with overlay edit icon.

Provides `avatar_upload/1` — a compact click-to-upload zone designed for
profile pictures and avatars. When an existing photo URL is provided, it is
shown as the background image with a semi-transparent overlay containing a
camera icon on hover. When a new file is selected via LiveView's upload
system, the `live_img_preview/1` helper renders an instant local preview.

## Requirements

The parent LiveView must configure the upload with `allow_upload/3`:

    def mount(_params, _session, socket) do
      {:ok,
       socket
       |> allow_upload(:avatar,
         accept: ~w(.jpg .jpeg .png .webp .gif),
         max_entries: 1,
         max_file_size: 5_242_880
       )}
    end

## Basic usage

    <%!-- Profile photo upload --%>
    <.avatar_upload
      upload={@uploads.avatar}
      current_url={@user.avatar_url}
      on_cancel="cancel_avatar"
    />

## With shape and size variants

    <.avatar_upload
      upload={@uploads.avatar}
      current_url={@user.avatar_url}
      shape="square"
      size="lg"
    />

## Handling cancel

    def handle_event("cancel_avatar", %{"ref" => ref}, socket) do
      {:noreply, cancel_upload(socket, :avatar, ref)}
    end

# `avatar_upload`

Renders a profile photo upload zone with optional existing image preview.

Layout:
1. If entries exist → `live_img_preview/1` of the first pending entry + remove button
2. If no entries → click-to-upload zone showing `current_url` (or a placeholder icon)
3. In both cases, a camera overlay icon is shown on hover

## Examples

    <.avatar_upload upload={@uploads.avatar} current_url={@user.photo_url} />

    <.avatar_upload upload={@uploads.avatar} shape="square" size="lg" />

## Attributes

* `upload` (`:any`) (required) - A `Phoenix.LiveView.UploadConfig` struct from `@uploads.field_name`.
* `current_url` (`:string`) - URL of the currently saved photo. Shown as background until a new file is selected. Defaults to `nil`.
* `shape` (`:string`) - Shape of the upload zone — `circle` (rounded-full) or `square` (rounded-lg). Defaults to `"circle"`. Must be one of `"circle"`, or `"square"`.
* `size` (`:string`) - Controls the width/height of the upload zone. Defaults to `"md"`. Must be one of `"sm"`, `"md"`, `"lg"`, or `"xl"`.
* `on_cancel` (`:string`) - LiveView event name fired when the remove (×) button is clicked. Defaults to `"cancel_upload"`.
* `class` (`:string`) - Additional CSS classes applied to the outer wrapper. Defaults to `nil`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*