05 · Forms — dates and values

Upload

drop zone (normal, dragging, error) · list with progress, done and failure · compact · button

File upload: a drop zone + a list with progress per file.

Dragging and uploading

Arraste os arquivos ou escolha no computador PDF, XML ou CSV · até 10 MB cada
XML
nfe-48211.xml Enviando…
CSV
extrato-bb-out.csv Enviando…
.heex
<div class="grid grid-cols-2 gap-[16px]"><.upload_drop loop hint="PDF, XML ou CSV · até 10 MB cada" drop_label="Arraste os arquivos ou" browse_label="escolha no computador" /><div class="flex flex-col gap-[8px]"><.upload_file loop name="nfe-48211.xml" status="Enviando…" progress={60} remove_label="Remover" /><.upload_file loop name="extrato-bb-out.csv" status="Enviando…" progress={60} remove_label="Remover" /></div></div>

drop zone states

Arraste os arquivos ou escolha no computador PDF, XML ou CSV · até 10 MB cada
Arraste os arquivos ou escolha no computador PDF, XML ou CSV · até 10 MB cada
.heex
<div class="grid grid-cols-2 gap-[16px]"><.upload_drop hint="PDF, XML ou CSV · até 10 MB cada" drop_label="Arraste os arquivos ou" browse_label="escolha no computador" /><.upload_drop over hint="PDF, XML ou CSV · até 10 MB cada" drop_label="Arraste os arquivos ou" browse_label="escolha no computador" /></div>

list

XML
nfe-48211.xml 32 KB · 64%
PDF
danfe-48211.pdf 212 KB · concluído
CSV
planilha-clientes.csv Linha 214: CNPJ inválido
.heex
<div class="flex flex-col gap-[8px]"><.upload_file name="nfe-48211.xml" status="32 KB · 64%" progress={64} remove_label="Remover" /><.upload_file name="danfe-48211.pdf" status="212 KB · concluído" progress={100} state="done" /><.upload_file name="planilha-clientes.csv" status="Linha 214: CNPJ inválido" progress={64} state="error" retry_label="Tentar de novo" /></div>

compact and button

nenhum arquivo escolhido
.heex
<div class="flex flex-wrap items-center gap-2.5"><.button color="neutral" variant="outline" size="md" shape="rounded" icon="attach">Anexar arquivo</.button><.button color="neutral" variant="solid" size="md" shape="rounded" icon="upload">Importar CSV</.button><span class="text-xs text-muted">nenhum arquivo escolhido</span></div>

API values that complete the parity

Arraste ou escolha
variant=canvas
Arraste ou escolha
variant=pond
Arraste ou escolha
variant=solid
Arraste ou escolha
variant=glow
Arraste ou escolha
variant=outline
Arraste ou escolha
variant=soft
Arraste ou escolha
variant=bordered
Arraste ou escolha
variant=flat
Arraste ou escolha
variant=glass
Arraste ou escolha
variant=dim
Arraste ou escolha
color=neutral
Arraste ou escolha
color=primary
Arraste ou escolha
color=secondary
Arraste ou escolha
color=info
Arraste ou escolha
color=success
Arraste ou escolha
color=warning
Arraste ou escolha
color=error
Arraste ou escolha
color=mono
Arraste ou escolha
color=white
Arraste ou escolha
color=current
Arraste ou escolha
shape=pill
Arraste ou escolha
shape=square
Arraste ou escolha
size=xl
Arraste ou escolha
layout=panel
layout=thumbs
columns=1
columns=3
columns=4
.heex
<div class="flex flex-col gap-[16px]"><div class="grid grid-cols-5 gap-[14px]"><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="canvas" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=canvas</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="pond" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=pond</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="solid" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=solid</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="glow" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=glow</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="outline" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=outline</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=soft</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="bordered" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=bordered</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="flat" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=flat</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="glass" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=glass</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="dim" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">variant=dim</span></div></div><div class="grid grid-cols-5 gap-[14px]"><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="neutral" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=neutral</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="primary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=primary</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="secondary" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=secondary</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="info" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=info</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="success" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=success</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="warning" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=warning</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="error" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=error</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="mono" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=mono</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="white" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=white</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="soft" color="current" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">color=current</span></div></div><div class="grid grid-cols-5 gap-[14px]"><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="bordered" color="primary" shape="pill" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">shape=pill</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="bordered" color="primary" shape="square" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">shape=square</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="bordered" color="primary" size="xl" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">size=xl</span></div><div class="flex flex-col items-start gap-1.5"><.upload_zone variant="canvas" color="neutral" style="width:100%">Arraste ou escolha</.upload_zone><span class="font-mono text-[11px] text-muted">layout=panel</span></div><div class="flex flex-col items-start gap-1.5"><.upload_thumbs /><span class="font-mono text-[11px] text-muted">layout=thumbs</span></div></div><div class="grid grid-cols-3 gap-[14px]"><div class="flex flex-col items-start gap-1.5"><.upload_thumbs columns={1} count={1} /><span class="font-mono text-[11px] text-muted">columns=1</span></div><div class="flex flex-col items-start gap-1.5"><.upload_thumbs columns={3} count={3} /><span class="font-mono text-[11px] text-muted">columns=3</span></div><div class="flex flex-col items-start gap-1.5"><.upload_thumbs columns={4} count={4} /><span class="font-mono text-[11px] text-muted">columns=4</span></div></div></div>

A finished entry with a remove button

PDF
danfe-48211.pdf 212 KB · concluído
XML
nfe-48211.xml 32 KB · 64%
.heex
<div class="flex flex-col gap-[8px]">
  <.upload_file name="danfe-48211.pdf" status="212 KB · concluído" progress={100} state="done" on_remove="remove" ref="danfe-48211" remove_label="Remover" />
  <.upload_file name="nfe-48211.xml" status="32 KB · 64%" progress={64} on_remove="remove" ref="nfe-48211" remove_label="Remover" />
</div>

Usage

<.upload upload={@uploads.notas} label="Notas fiscais" accept=".pdf,.xml" max_entries={10} />
<.upload upload={@uploads.logo} variant="button" />

Rules

  • Dragging over: teal border and soft background.
  • Each file shows the bar until it finishes; a failure turns red and asks to try again.

API reference

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

File uploads built on LiveView uploads: the drop panel with each file's progress, errors and cancel button (shown on finished entries too, so a sent file can be removed before submitting), and the styled "Choose File" button.

# mount
socket |> allow_upload(:photos, accept: ~w(.jpg .png), max_entries: 4)

<.form for={@form} phx-change="validate" phx-submit="save">
  <.upload upload={@uploads.photos} on_cancel="cancel-upload" columns={2}
    hint="PDF, XML ou CSV · até 10 MB cada" />
</.form>

def handle_event("cancel-upload", %{"ref" => ref}, socket),
  do: {:noreply, cancel_upload(socket, :photos, ref)}

upload/1 renders live_file_input itself, so it must sit inside the form that has the phx-change LiveView uploads need. Dropping files on the panel works through phx-drop-target; the LedgerUI.Upload hook (priv/static/ledger_ui/hooks/upload.js) only sets data-state="over" (which paints the over state) while files are dragged over it.

The pieces it is made of are public and stateless, for custom layouts and for the design gallery: upload_drop/1 (the dashed drop area), upload_zone/1 (the compact zone with the kit's variants), upload_file/1 (a file card), upload_thumbs/1 and upload_button/1.

Deviation from the README: upload_button/1 is a <label> around the file input (as the README says), so the design's <button> is not reproduced byte for byte; variant accepts the design's zone variants too (solid glow outline soft bordered flat glass dim).

<.upload_drop>

The dashed drop area: icon, label with the browse link, and a hint.

Attr Type Default Values / notes
drop_label :string "Drag & Drop your files or"
browse_label :string "Browse"
hint :string nil
over :boolean false Draws the drag-over state.
error :boolean false
loop :boolean false The canvas demo animation: the area takes the drag-over look and lets go, every 5s.
circle :boolean false A round area (the circle layout).
for :string nil Id of the file input: the area becomes its <label>.
icon_path :string nil
class :any nil

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

Slots:

  • <:label> - Replaces the text of the area.

<.upload_zone>

The compact drop zone with the kit's variants, colors, shapes and sizes.

Attr Type Default Values / notes
variant :string "canvas" canvas, pond, solid, glow, outline, soft, bordered, flat, glass, dim
color :string "primary" neutral, primary, secondary, info, success, warning, error, mono, white, current
shape :string "rounded" rounded, pill, square
size :string nil nil, md, xl
for :string nil
class :any nil

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

Slots:

  • <:inner_block> (required)

<.upload_file>

A file card: badge, name, status, progress bar and the remove (or retry) button.

Attr Type Default Values / notes
name (required) :string
ext :string nil The badge text (XML); the extension of name by default.
status :string nil The line under the name.
progress :integer 0
loop :boolean false The canvas demo animation: the progress bar fills from 0 to 100%, every 4s.
state :string "progress" progress, done, error
remove_label :string "Remove"
retry_label :string nil On an error: a retry button with this text.
removable :boolean true
on_remove :any nil An event name or a %JS{} for the remove button. It also shows next to the check on finished (done) cards.
on_retry :any nil
ref :string nil Sent as phx-value-ref with the events.
target :any nil
class :any nil

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

Slots:

  • <:preview> - Replaces the extension badge (an image preview).

<.upload_thumbs>

The grid of 64px thumbnails.

Attr Type Default Values / notes
count :integer 3
columns :integer nil --cols (3 by default).
class :any nil

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

Slots:

  • <:inner_block> - Your own tiles instead of count placeholders.

<.upload_button>

A button that opens the file chooser: a <label> with the button classes holding an invisible file input. With upload it renders live_file_input; otherwise a plain <input type="file">.

<.upload_button upload={@uploads.avatar}>Choose File</.upload_button>
<.upload_button name="doc" variant="outline" size="sm">Attach</.upload_button>
Attr Type Default Values / notes
upload {:struct, Phoenix.LiveView.UploadConfig} nil
name :string nil
multiple :boolean false
accept :string nil
disabled :boolean false
color :string "neutral" neutral, primary, secondary, info, success, warning, error, mono, white, current
variant :string "solid" solid, glow, outline, soft, bordered, flat, glass, ghost, dim
size :string nil nil, `,xs,sm,md,lg,xl`
shape :string "rounded" rounded, pill, square
icon :boolean false
class :any nil

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

Slots:

  • <:inner_block> (required)

<.upload>

Renders the drop panel and the list of chosen files.

Attr Type Default Values / notes
upload (required) {:struct, Phoenix.LiveView.UploadConfig}
id :string nil
bordered :boolean false
filled :boolean false
columns :integer 1 1, 2, 3, 4
variant :string "canvas" canvas, pond, solid, glow, outline, soft, bordered, flat, glass, dim
color :string "primary" neutral, primary, secondary, info, success, warning, error, mono, white, current
shape :string "rounded" rounded, pill, square
size :string nil nil, md, xl
layout :string "panel" panel, circle, thumbs
hint :string nil
browse :string nil
icon_path :string nil
drop_class :any nil
on_cancel :any nil
target :any nil
previews :boolean true
error_texts :map %{too_large: "File is too large", too_many_files: "Too many files", external_client_failure: "Upload failed", not_accepted: "File of invalid type"}
browse_label :string "Browse"
drop_label :string "Drag & Drop your files or"
remove_label :string "Remove"
uploading_label :string "Uploading"
complete_label :string "Upload complete"
class :any nil

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

Slots:

  • <:label> - Replaces the text of the drop panel.