Upload
<sea-upload> supplies documents to a labelled extraction step in an existing pipeline run.
| At a glance | |
|---|---|
| Type | Building block |
| Element | sea-upload |
| React | SeaUpload from @sea-dev/widget-lit/react/upload |
| Without React | @sea-dev/widget-lit/upload |
| Connection | An ancestor Context provider |
| Configure | Attributes and properties |
Usage
Place SeaUpload inside a process and set stepLabel to the extraction step's unique label, such as trade-licence, memorandum or financial-statements. The widget resolves that step's missing_upload dependency from the existing run.
Within a step group, uploads inherit its binding. An explicit label on the uploader overrides that binding. A label that resolves to another role disables the uploader and identifies the selected step and its role in a configuration message.
tsx
import * as React from "react";
import { SeaContextProvider } from "@sea-dev/widget-lit/react/context";
import { SeaProcess } from "@sea-dev/widget-lit/react/process";
import { SeaUpload } from "@sea-dev/widget-lit/react/upload";
export function Uploads(p: {
apiUrl: string;
bearerToken: string;
runId: string;
}) {
return (
<SeaContextProvider apiUrl={p.apiUrl} bearerToken={p.bearerToken}>
<SeaProcess runId={p.runId}>
<SeaUpload
stepLabel="financial-statements"
formats="pdf,images,spreadsheets"
maxSizeMb={20}
multiple
/>
</SeaProcess>
</SeaContextProvider>
);
}Set the API URL and credential on the required Sea context. The process and its children reuse that client. Uploads need no host-managed form, submission or extraction IDs.
The widget manages batch uploads and retries, then refreshes the process so bound forms and source viewers receive the run's outputs. Other blockers, such as parent_incomplete, can still prevent the step from running. Use manual input for a manual step's required form.
Partially accepted files stay staged. The Retry batch action retains the original batch and its identity. A committed batch waits for its selected step to run before showing processing progress; the step's completion determines when processing is done.
Choosing another output or source document keeps an accepted batch attached to its original run step. Your application starts the run before mounting the widgets. To supply documents from a server, see Upload documents.
Attributes and properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
formId | form-id | string or undefined | — | Selects the form for standalone submission uploads, overriding run-step uploads when set directly. |
dealId | deal-id | string or undefined | — | Selects the existing deal for a new standalone submission. |
submissionId | submission-id | string or undefined | — | Uploads into this standalone submission, overriding run-step uploads when set directly. |
model | model | ExtractionModel | "general" | Selects general, smart, bank_statement, financials or agentic_analyst extraction for standalone submission uploads. |
multiple | multiple | boolean | false | Allows more than one file per upload batch. |
multipleFiles | multiple-files | DocumentsMultipleFiles or undefined | — | Sets enabled or disabled for multiple-file selection, taking precedence over multiple and maxCount. |
formats | formats | string or string[] or undefined | — | Sets accepted file types using presets, extensions or MIME types supplied as a comma-separated string or an array. |
maxSizeMb | max-size-mb | number or undefined | — | Limits each file's size in megabytes, up to the API's upload limit. |
maxCount | max-count | number or undefined | — | Limits the total number of documents, including existing documents and files in the current batch. |
existingCount | existing-count | number | 0 | Supplies the total existing-document count when the host has a broader inventory than the mapped sources. |
existingFileNames | — | readonly string[] | [] | Supplies additional existing filenames for duplicate detection alongside mapped sources. |
existingDocumentIds | — | readonly string[] | [] | Identifies completed uploads already included in existingCount so they count only once towards maxCount. |
zeroFieldDocumentIds | — | readonly string[] | [] | Marks completed uploads the extraction read nothing from, replacing their "Done" status with a truthful one. |
onDuplicate | on-duplicate | "add" or "reject" | "add" | Controls whether duplicate uploads are added again or rejected. |
stepRole | step-role | PipelineStepRoleWire or undefined | — | Constrains the selected step to this pipeline role. |
stepLabel | step-label | string or undefined | — | Selects one step by its unique pipeline label within the enclosing process. |
stepId | step-id | string or undefined | — | Selects a pipeline step definition within the enclosing process. |
runStepId | run-step-id | string or undefined | — | Selects one executable step instance within the enclosing process. |
outputFormId | output-form-id | string or undefined | — | Narrows the selected step's outputs to this form. |
outputSubmissionId | output-submission-id | string or undefined | — | Selects an exact output submission from the enclosing process. |
Events
| Event | Type | Description |
|---|---|---|
documents-uploaded | CustomEvent | The exact pipeline document batch receipt, with outcome distinguishing staging from a committed step attachment. |
upload-started | CustomEvent | { fileName } after local validation, before an API upload attempt. |
submission-created | CustomEvent | { submissionId } after creating a standalone submission for the first upload. |
upload-accepted | CustomEvent | { submissionId, fileName, documentId, extractionId } when one standalone submission upload is accepted. |
upload-failed | CustomEvent | { fileName, error, acceptance, code?, documentId?, extractionId?, status? } when an attempted API upload fails, including when submission creation fails for the batch, with code identifying a per-file upload failure and acceptance set to unknown or rejected. |
processing-error | CustomEvent | { submissionId, extractionId, fileName, error, status? } when one standalone extraction fails. |
processing-complete | CustomEvent | { submissionId, results } when all standalone submission uploads finish. Each result includes its status and filename. |
documents-uploaded reports the run-step batch receipt. Observing events is optional; the widgets coordinate uploads and run refreshes themselves. Extraction events such as upload-accepted and processing-complete belong to submission compatibility mode. Upload documents defines committed, partial and uncertain outcomes.
File limits
formats accepts these presets, file extensions or MIME types. The default presets are pdf, images and spreadsheets.
| Preset | Extensions | MIME types |
|---|---|---|
pdf | .pdf | application/pdf |
images | .png, .jpg, .jpeg | image/png, image/jpeg |
spreadsheets | .xlsx, .xls, .csv | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, text/csv |
text | .txt | text/plain |
Each preset expands to the listed extensions. The API accepts multipart files without an extension or MIME-type allowlist; formats restricts the widget's file selection.
maxSizeMb limits each file, up to 100 MB. maxCount includes existing and pending documents. onDuplicate="reject" compares tracked filenames and sizes, and filenames in existingFileNames.
multipleFiles="enabled" permits several files in a batch for the same selected step. The uploader counts documents in its mapped scope. Unrelated steps' documents do not consume that scope's cap.
API and transport
Run-bound uploads use pipeline.uploadDocuments through the context's client. This operation supplies documents directly to the selected extraction step.
Custom transports must implement that operation alongside the process's read operations. Upload documents documents the request, receipts and safe retries.
Existing submission uploads
Setting formId or submissionId directly on SeaUpload selects submission compatibility mode, including inside a process. Ancestor form or submission metadata does not switch a run-bound upload into this mode. Use formId with dealId to create a submission, or submissionId to add files to an existing one. This mode uses the submission upload API and extraction status reads.
The previous upload names remain compatibility aliases. Use the canonical upload names for new integrations.
Styling parts
| Part | Description |
|---|---|
root | The upload container. |
dropzone | The file drop and browse control. |
content | The accepted file list. |
item | An individual upload. |
status | Upload progress and error messages. |
Common problems
| Symptom | Action |
|---|---|
| File rejected before upload | Check the displayed type, size or duplicate reason |
| Upload fails | Read upload-failed.detail.error and its HTTP status |
| Receipt is partial or lost | Retain the batch and use the widget's retry action |
| Step does not run | Check its remaining blockers in the process |