Upload widget

The upload widget is a drop-in upload box for your website. Use it when people outside your workspace need to send you files, such as artwork from customers, documents from applicants, or an updated logo from a partner, and you do not want to build an upload backend. You configure it in the dashboard, paste two lines of HTML into your site, and uploads land in a bucket you choose or replace one specific file. By default nothing goes live until someone in your workspace approves it.

Create a widget#

1. Open Share > Upload widgets and choose New widget.
2. Give it a Name your team will recognize in the review queue, such as Website contact form.
3. Under Uploads go to, choose:
   • New files in a bucket to collect new files, then pick the Bucket.
   • Replace one file to let visitors send a new version of one existing file, then pick the File to replace. Approving an upload publishes it as the next revision behind that file's existing link.
4. Choose the accepted file types and the Max size (MB).
5. List the Websites allowed to embed, one per line, for example https://example.com.
6. Leave Review each upload before it goes live on unless you fully trust everyone who can reach the page.
7. Save, then choose Copy embed code on the widget's card.

The number of active widgets depends on your plan (one on Free). A paused widget does not count; use Pause widget to stop accepting uploads without deleting the configuration.

Embed it#

Paste the embed code where the upload box should appear. It looks like this:

<div
  data-steadylink-widget="wdg_8Zk3pQ..."
  data-api="https://api.steadylink.io"
  data-button-text="Send artwork"
  data-accept="image/*,.pdf"
  data-max-bytes="26214400"
  data-theme="light"
></div>
<script async src="https://steadylink.io/widget/v1.js"></script>

The script finds every element with data-steadylink-widget when the page loads and renders an upload box inside it (in a shadow root, so your site's CSS does not leak in). The box has a button, a drop zone, a progress bar, and a status line announced to screen readers.

data-accept and data-max-bytes only improve the visitor's experience. The rules that matter are the ones saved on the widget, and SteadyLink enforces them on its side for every upload. Editing the attributes in a browser does not bypass them.

Pages that render later#

If your page adds the element after load (a modal, a client-side route, a React component), mount it yourself once the script has loaded:

window.SteadyLinkUpload.mount(document.querySelector("#artwork-upload"));
// or re-scan the whole page
window.SteadyLinkUpload.scan();

Mounting the same element twice is ignored, so calling scan() after every route change is safe.

React to completed uploads#

When an upload finishes, the element dispatches a steadylink:complete event that bubbles, and calls the data-callback function if you set one. The event's detail is the completion result:

document.querySelector("[data-steadylink-widget]").addEventListener("steadylink:complete", (event) => {
  const { status, assetId } = event.detail;
  if (status === "awaiting_approval") {
    showMessage("Thanks. We will review your file shortly.");
  } else {
    showMessage(`Received. File ID ${assetId}`);
  }
});

document.querySelector("[data-steadylink-widget]").addEventListener("steadylink:error", (event) => {
  console.warn("Upload failed:", event.detail.message);
});

The widget also updates its own status line ("Submitted for review" or "Upload complete"). steadylink:error fires when validation, the transfer, or completion fails, with detail.message describing the failure.

Security and upload flow#

The widget never sees a workspace API key or storage credentials. Each upload works like this:

1. The browser asks POST /api/public/widgets/{public_key}/initialize for a session, sending the file's name, size, and type. SteadyLink checks that the request's Origin is on the widget's list, that the widget is active, and that the file fits the widget's type and size rules and your plan's limits.
2. It answers with a ten-minute, origin-bound session with one create or replace permission: a one-time session token and a presigned upload URL that both expire after ten minutes.
3. The browser PUTs the bytes directly to that URL with Content-Type: application/octet-stream.
4. The browser calls POST /api/public/widgets/{public_key}/complete with the session token as Authorization: Bearer. The request must come from the same origin that started the session, and the stored file must be exactly the declared size.
5. The session is consumed at that moment and cannot be replayed. The upload either waits for review or is published.

Origins are matched on scheme, host, and port only. https://example.com, https://www.example.com, and http://example.com are three different origins, so list every variant your site is served from. A widget accepts up to 30 origins. Paths are not allowed in an origin, and pages on any path of a listed origin can use the widget.

Because the public key is visible in your page's HTML, anyone can copy the embed code. The origin check stops other websites from using it in a browser, but it cannot stop a determined person sending requests from a script with a forged Origin header. That is the reason review is on by default.

Review uploads before they go live#

With Review each upload before it goes live on, completed uploads stay in temporary storage. They do not appear in your buckets and do not change any live file until a workspace member approves them. Your workspace is notified with "Widget upload needs approval".

Open Share and go to the Review queue to preview each upload, download it, and choose Approve or Reject:

• Approve on a New files widget adds the file to the widget's bucket, in a folder called widget-submissions/, where it is finalized and scanned like any upload. On a Replace one file widget it publishes the upload as the next revision of the target file, so the file's existing link starts serving it.
• Reject deletes the temporary file. This cannot be undone.

Uploads waiting for review expire after seven days and can no longer be approved. Deleting a widget also deletes any uploads still waiting for review. Approvals and rejections are also available through the Sharing API.

Publishing without review#

Turning review off publishes each upload as soon as it completes: new files go to the root of the widget's bucket, and replacements go live behind the target file's link. The dashboard warns you that "Files sent through this widget will go live as soon as they finish uploading."

Uploaded files are scanned for malware either way, and a file that fails the scan is never served.

Limits#

Troubleshooting#

Open Share to check the widget's origins and rules, then load your page from exactly one of the listed origins. You can try a widget on the example page once its origin list includes https://steadylink.io.

Next steps#