File Upload Card

The file upload card lets the user select a file in the browser and upload it to an HTTP endpoint on the device. The card shows upload progress and whether the upload succeeded. Use it to transfer configuration files, data files or other assets to the device.

ConstructorCopy Anchor Link

template <typename T = dash::string>
dash::FileUploadCard<T>(ESPDash& dashboard, const char* name, const char* extensions = "");

Template parametersCopy Anchor Link

ParametersCopy Anchor Link

dash::FileUploadCard<> fileUpload(dashboard, "Upload", ".txt");

An overload without the dashboard argument creates the card without attaching it to a dashboard; attach it later with dashboard.add(card).

How uploads workCopy Anchor Link

The card does not receive file data itself and has no callback. When the user selects a file, the browser sends it to the URL set with setValue():

• One file is uploaded per selection.
• The request is an HTTP POST with a multipart/form-data body; the file is in the form field named file.
• The card shows a success indicator if the endpoint responds with status 200, and an error indicator for any other status.

You must register a handler for the upload URL on the AsyncWebServer instance and process the incoming data there, for example by writing it to a file system. See the example below.

MethodsCopy Anchor Link

setValue()Copy Anchor Link

bool setValue(T url);

Sets the URL the file is uploaded to. Returns true if the value changed.

fileUpload.setValue("/upload");

value()Copy Anchor Link

const T& value() const;

Returns the current upload URL.

setExtensions()Copy Anchor Link

bool setExtensions(const char* extensions);

Sets the file types offered in the browser's file selection dialog, as a comma-separated list of file extensions or MIME types. Returns true if the value changed.

fileUpload.setExtensions(".txt,.jpg");

extensions()Copy Anchor Link

const char* extensions() const;

Returns the current list of accepted file extensions or MIME types.

ExampleCopy Anchor Link

#include <Arduino.h>
#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <ESPDashPro.h>

AsyncWebServer server(80);
ESPDash dashboard(server);

dash::FileUploadCard<> fileUpload(dashboard, "Upload", ".txt");

void setup() {
  Serial.begin(115200);
  // ... connect to WiFi

  fileUpload.setValue("/upload");

  // Handle the upload request sent by the card
  server.on(
    "/upload",
    HTTP_POST,
    [](AsyncWebServerRequest* request) {
      // Called once the upload is complete; status 200 marks it as successful
      request->send(200);
    },
    [](AsyncWebServerRequest* request, String filename, size_t index, uint8_t* data, size_t len, bool final) {
      if (index == 0) {
        Serial.printf("Upload start: %s\n", filename.c_str());
        // ... open the destination file
      }
      // ... write `len` bytes from `data`
      if (final) {
        Serial.printf("Upload end: %s, %u bytes\n", filename.c_str(), (unsigned)(index + len));
        // ... close the destination file
      }
    });

  server.begin();
}

void loop() {
  // ...
}

NotesCopy Anchor Link

• The file type filter applies only to the browser's selection dialog. Validate the file name, type and size in your upload handler.
• The card stores the extensions pointer and does not copy the string. Pass a string literal or a buffer that remains valid for the lifetime of the card.