File field

The file_field component renders a standard file input. A plain input needs a name, or a field to take the name from, like every other field in this kit. With field={@form[:resume]} the name, the id and the errors come from the form. label draws a label that points at the input's id, so pass an id or a field, which brings one. With the dropzone option it becomes a drag-and-drop area for LiveView uploads, so the user can drop files into it as well as click to choose them.

<.file_field id="attachment-base" name="attachment" label="Base" color="base" />
<.file_field id="attachment-natural" name="attachment" label="Natural" color="natural" />
<.file_field id="attachment-white" name="attachment" label="White" color="white" />
<.file_field id="attachment-primary" name="attachment" label="Primary" color="primary" />
<.file_field id="attachment-secondary" name="attachment" label="Secondary" color="secondary" />
<.file_field id="attachment-dark" name="attachment" label="Dark" color="dark" />
<.file_field id="attachment-success" name="attachment" label="Success" color="success" />
<.file_field id="attachment-warning" name="attachment" label="Warning" color="warning" />
<.file_field id="attachment-danger" name="attachment" label="Danger" color="danger" />
<.file_field id="attachment-info" name="attachment" label="Info" color="info" />
<.file_field id="attachment-misc" name="attachment" label="Misc" color="misc" />
<.file_field id="attachment-dawn" name="attachment" label="Dawn" color="dawn" />
<.file_field id="attachment-silver" name="attachment" label="Silver" color="silver" />

<.file_field field={@form[:resume]} label="Attach your résumé" />

Set live and pass the upload in upload to use the plain file input for a LiveView upload. upload is required with live. The component draws the upload's own input and ties the label to it, so a click on the label opens the file picker. With live or dropzone the id is written on the outer element, because the input itself is identified by the upload's ref.

The form below is a demo form: it registers one upload and hands it to the field, so only label and color are written on the field here.

<.file_field live upload={@uploads.avatar} label="Avatar" color="primary" />

# In your LiveView
def mount(_params, _session, socket) do
  {:ok, allow_upload(socket, :avatar, accept: ~w(.jpg .jpeg .png), max_entries: 1)}
end

Set the dropzone boolean to replace the plain file input with a drag-and-drop area. A dropzone is made for LiveView uploads: pass the name of the upload in target and the upload map in uploads, as in the code below. The dropzone is a label for the upload's input, so a click anywhere in it opens the file picker. The component lists the selected files while they upload, and shows the upload errors, such as a file that is too large or too many files. Its cancel button sends a cancel-upload event with the file's ref, which your LiveView answers with cancel_upload/3.

<.file_field target={:resume} uploads={@uploads} dropzone />

# In your LiveView
def mount(_params, _session, socket) do
  {:ok, allow_upload(socket, :resume, accept: ~w(.pdf .jpg .jpeg .png), max_entries: 3)}
end

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

The dropzone_type prop is file by default, or image. With file, every selected file is a row with its name, its size in MB, a progress bar and a cancel button. With image, every file is a small thumbnail with a cancel button and a spinner while it uploads. The form below uses image; choose a picture to see its thumbnail.

<%!-- The default is dropzone_type="file" --%>
<.file_field target={:resume} uploads={@uploads} dropzone dropzone_type="file" />

<.file_field target={:avatar} uploads={@uploads} dropzone dropzone_type="image" />

The dropzone component provides a convenient and customizable area for file uploads, allowing users to add unique icons, titles, and descriptions. By setting the dropzone_icon attribute, you can specify any Heroicon icon to replace the default cloud upload symbol, giving it a personal touch or matching the application's theme. The dropzone_title attribute offers a clear prompt, such as “Click to upload, or drag and drop a file,” helping users understand how to interact with the component. Additionally, the dropzone_description attribute allows for an optional description, which can specify file size limits, accepted file types, or other upload requirements. This added customization helps users upload files confidently by making the process intuitive and guided.

<.file_field
  target={:documents}
  uploads={@uploads}
  dropzone
  dropzone_icon="hero-arrow-up-tray"
  dropzone_title="Upload your documents here"
  dropzone_description="Supports PDF files up to 500 KB"
/>

The dropzone takes a variant and a color. The variants are base (the default), outline, default, shadow, bordered, gradient and transparent. outline draws the border in the color, default fills the dropzone with it, shadow adds a colored shadow to the fill, bordered uses a tint of the color with a border, gradient fills it with a gradient and transparent has no fill. The colors are base (the default), natural, white, primary, secondary, dark, success, warning, danger, info, misc, dawn and silver. Give every dropzone its own upload: two dropzones on one upload would share a single input.

<.file_field target={:outline_upload} uploads={@uploads} variant="outline" color="primary" dropzone />
<.file_field target={:default_upload} uploads={@uploads} variant="default" color="success" dropzone />
<.file_field target={:gradient_upload} uploads={@uploads} variant="gradient" color="misc" dropzone />
<.file_field target={:avatar} uploads={@uploads} variant="base" color="base" dropzone />