PhiaUi.Components.AvatarUpload (phia_ui v0.1.17)

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

Summary

Functions

avatar_upload(assigns)

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

Functions

avatar_upload(assigns)

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

Layout:

If entries exist → live_img_preview/1 of the first pending entry + remove button
If no entries → click-to-upload zone showing current_url (or a placeholder icon)
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.