05 · Forms — dates and values

ImageInput

shape square · circle · wide × empty · with image · pointer over · uploading

A single image (logo, profile photo, cover): click to choose, shows the preview and the upload progress.

Switch and send

BP
AN
.heex
<div class="flex flex-wrap items-center gap-2.5"><.image_input id="ii-loop-hover" shape="square" initials="BP" loop="hover" /><.image_input id="ii-loop-ring" initials="AN" loop="ring" /></div>

shape × state

vaziocom imagemhoverenviandosquare
BP
BP
BP
circle
BP
BP
BP
wide
BP
BP
BP
.heex
<div class="grid grid-cols-[80px_repeat(4,_minmax(0,1fr))] gap-y-[10px] gap-x-[12px] items-center"><span></span><span class="text-xs text-muted font-mono text-center">vazio</span><span class="text-xs text-muted font-mono text-center">com imagem</span><span class="text-xs text-muted font-mono text-center">hover</span><span class="text-xs text-muted font-mono text-center">enviando</span><span class="text-xs text-muted font-mono">square</span><div class="flex justify-center min-w-0"><.image_input id="ii-square-0" shape="square" /></div><div class="flex justify-center min-w-0"><.image_input id="ii-square-1" shape="square" initials="BP" /></div><div class="flex justify-center min-w-0"><.image_input id="ii-square-2" shape="square" initials="BP" hover /></div><div class="flex justify-center min-w-0"><.image_input id="ii-square-3" shape="square" initials="BP" progress={62} /></div><span class="text-xs text-muted font-mono">circle</span><div class="flex justify-center min-w-0"><.image_input id="ii-circle-0" shape="circle" /></div><div class="flex justify-center min-w-0"><.image_input id="ii-circle-1" shape="circle" initials="BP" /></div><div class="flex justify-center min-w-0"><.image_input id="ii-circle-2" shape="circle" initials="BP" hover /></div><div class="flex justify-center min-w-0"><.image_input id="ii-circle-3" shape="circle" initials="BP" progress={62} /></div><span class="text-xs text-muted font-mono">wide</span><div class="flex justify-center min-w-0"><.image_input id="ii-wide-0" shape="wide" /></div><div class="flex justify-center min-w-0"><.image_input id="ii-wide-1" shape="wide" initials="BP" /></div><div class="flex justify-center min-w-0"><.image_input id="ii-wide-2" shape="wide" initials="BP" hover /></div><div class="flex justify-center min-w-0"><.image_input id="ii-wide-3" shape="wide" initials="BP" progress={62} /></div></div>

API values that complete the parity

size=sm
size=md
size=xl
shape=rounded
.heex
<div class="grid grid-cols-4 gap-[14px]"><div class="flex flex-col items-start gap-1.5"><.image_input id="ii-sm" shape="square" size="sm" /><span class="font-mono text-[11px] text-muted">size=sm</span></div><div class="flex flex-col items-start gap-1.5"><.image_input id="ii-md" shape="square" size="md" /><span class="font-mono text-[11px] text-muted">size=md</span></div><div class="flex flex-col items-start gap-1.5"><.image_input id="ii-xl" shape="square" size="xl" /><span class="font-mono text-[11px] text-muted">size=xl</span></div><div class="flex flex-col items-start gap-1.5"><.image_input id="ii-rd" shape="rounded" /><span class="font-mono text-[11px] text-muted">shape=rounded</span></div></div>

Try it: choose a file (with name)

AN
Clique na imagem para escolher um arquivo.
.heex
<div class="flex flex-wrap items-center gap-4">
  <.image_input id="ii-live-avatar" name="avatar" size="lg" initials="AN" />
  <.image_input id="ii-live-logo" name="logo" shape="rounded" />
  <span class="text-xs text-muted">Clique na imagem para escolher um arquivo.</span>
</div>

Usage

<.image_input upload={@uploads.avatar} shape="circle" />
<.image_input upload={@uploads.capa} shape="wide" label="Capa" help="1200×400, até 2 MB" />

Rules

  • Empty: dashed with an icon. With an image: solid border; Replace appears when the pointer is over.
  • Uploading: a progress ring over the preview.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

An image field: the picture (an avatar, a logo) in a round or rounded frame, with an edit overlay and a small button to remove or revert it.

<.image_input name="avatar" value={@user.avatar_url} size="lg" />
<.image_input name="logo" value="/images/logo.png" shape="rounded" />

With a name the frame is a file picker: clicking the picture opens the chooser, the chosen file shows at once and the button puts the first picture back or, with nothing chosen, empties the field and sets the hidden <name>_remove input to 1. The behaviour lives in the LedgerUI.ImageInput hook (priv/static/ledger_ui/hooks/image_input.js).

Without a name it is only the frame: initials draws a filled frame with letters, hover forces the edit overlay and progress draws the upload ring.

Deviations from the README: size has no default (nil is the design's 88px frame with a large icon, same as md) and shape accepts square (the design's default radius) and wide too.

<.image_input>

Renders the image field.

Attr Type Default Values / notes
id :string nil
name :string nil The name of the file input; <name>_remove is the hidden one.
value :string nil The address of the picture it holds now.
accept :string ".png,.jpg,.jpeg,.webp"
size :string nil nil, lg, md, sm, xl
shape :string "circle" circle, rounded, square, wide
label :string "Choose a picture"
remove_label :string "Remove or revert the picture"
initials :string nil Letters on a filled frame when there is no picture.
hover :boolean false Draws the edit overlay (the hover state).
loop :string nil nil, hover, ring - Animated demo of a state: hover loops the edit overlay, ring loops the upload ring.
progress :integer nil An upload ring, 0 to 100.
disabled :boolean false
class :any nil

Any other HTML/phx attribute goes to the root element.