Document auto_upload

[apohllo]

The docs are missing this code snippet which shows how to use the auto_upload feature.

allow_upload(socket, :avatar, accept: :any, progress: &handle_progress/3, auto_upload: true)

defp handle_progress(:avatar, entry, socket) do
  if entry.done? do
    uploaded_file =
      consume_uploaded_entry(socket, entry, fn %{} = meta ->
        {:ok, ...}
      end)

    {:noreply, put_flash(socket, :info, "file #{uploaded_file.name} uploaded")}
  else
    {:noreply, socket}
  end
end

[apohllo]

In Phoenix LiveView, you can trigger file processing immediately upon selection by enabling the auto_upload: true option. This removes the need for a traditional form submission to handle the files.

Immediate Processing with auto_upload

When auto_upload is enabled, the upload begins as soon as the user selects a file. To process the completed file without a submit event, you must use the progress callback to monitor the state of the entry.

auto_upload: true: Tells LiveView to start the transfer to the temporary storage location immediately.

handle_progress/3: This function is called every time the upload progress changes. You should check entry.done? to identify when the file is fully transferred.

Consumption: Call consume_uploaded_entry/3 inside the progress handler to move the file to its final destination or perform database operations.

# Initialize the upload with auto_upload enabled
allow_upload(socket, :avatar, accept: :any, progress: &handle_progress/3, auto_upload: true)

defp handle_progress(:avatar, entry, socket) do
  if entry.done? do
    # The file is fully uploaded to temp storage; consume it now
    uploaded_file =
      consume_uploaded_entry(socket, entry, fn %{} = meta ->
        # Perform file persistence logic here (e.g., move to S3 or local disk)
        {:ok, ...}
      end)

    {:noreply, put_flash(socket, :info, "file #{uploaded_file.name} uploaded")}
  else
    {:noreply, socket}
  end
end

Note: Because handle_progress runs for every chunk of data, always wrap your consumption logic in an if entry.done? block to ensure it only executes once.

[apohllo]

@chrismccord the example comes from the API. I know this is documented in the source file. Still I think it would be beneficial to add that to the upload description file. When searching in Google only the upload file and some forum threads talk about auto upload.

[SteffenDE]

@apohllo if you want, please have a look at #4130 and let me know if you think that's enough :)