For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/components/upload.md.
v0.0.57
  • English
  • Upload

    Data Entry@rockshin/tao-ui

    Select, drop and manage files with real requests, custom uploads and controlled lists.

    Choose from text, picture, picture-card and picture-circle lists. The examples below demonstrate local selection and explicitly simulated requests; connect action or customRequest to your own service for real uploads.

    Examples

    Click to select

    Start with completed and failed files. New selections stay local because beforeUpload returns false.

    project-brief.pdfrequirements.docxbudget.xlsxExample: the server rejected this file
    TSX

    Controlled file list

    Own fileList through onChange; the clear button updates the same state.

    TSX

    Validate and ignore files

    LIST_IGNORE excludes rejected files from the list. Browser accept is only a selection hint.

    TSX

    Multiple files and limits

    maxCount caps the list length; one replaces the current file.

    TSX

    Drag and drop

    Click anywhere in the drop zone or drop multiple files. Files stay local; no request is sent.

    Click or drag files to this areaSelect a single file or multiple documents.
    TSX

    Picture list

    A compact list with thumbnails, filenames and actions. Click a thumbnail to preview; new images stay local.

    image-01.pngimage-02.pngExample upload error
    TSX

    Picture wall with preview

    Controlled picture-card list with completed, uploading and failed examples. Preview and remove images; the trigger hides at six files. Uploading progress is an initial display state, not a running request.

    image-01.pngimage-02.pngLoading
    Example upload errorAdd image
    TSX

    Circular picture list

    The complete tile and its upload trigger are circular. Keyboard focus reveals the same actions as hover.

    profile.pngAdd image
    TSX

    Avatar selection

    Replace a single image without a file list. Validate image type and a 2 MB size limit before reading the local preview. This does not save an avatar to a server.

    Select avatar
    TSX

    Custom request and progress

    An explicit simulation with no network traffic: choose files to see progress, completion and cancellation. Enable the switch to simulate a failed request. Replace this customRequest with your transport in production.

    TSX

    Disabled upload

    Disable selection and removal while keeping completed files available for preview.

    image.pngAdd image
    TSX

    Confirm removal

    onRemove can reject removal synchronously or asynchronously. This example protects files with a switch.

    protected-report.pdf
    TSX

    Extra list information

    Render per-file information and choose which list actions appear.

    design-notes.pdf240 KB · local file
    TSX

    Phone selection and paste

    pastable accepts clipboard files. The browser and device control available file sources.

    390 × 640
    TSX

    API

    PropertyTypeDefaultDescription
    fileList / defaultFileListUploadFile[]—Controlled list / initial uncontrolled list.
    onChange({ file, fileList, event? }) => void—Called for selection, progress, completion, failure and removal.
    actionstring or (file) => string / PromiseLike<string>—Upload URL; required for the default transport.
    customRequest(options, { defaultRequest }) => void / { abort() }—Supply your transport; report progress, success or error through options.
    beforeUpload(file, files) => boolean / File / Blob / Promise—false stops the request but keeps the file; Upload.LIST_IGNORE excludes it; return File/Blob to transform.
    listType'text' / 'picture' / 'picture-card' / 'picture-circle''text'List appearance; card and circle triggers follow the file tiles.
    showUploadListboolean or ShowUploadListInterfacetrueConfigure extra content and preview, download and remove actions per file.
    maxCountnumber—Limit list length; 1 replaces the previous file. Hide the trigger yourself with children=.
    multiple / directory / pastablebooleanfalseMultiple selection / directory selection / clipboard file upload.
    acceptstring or AcceptConfig—Selection hint, such as image/*. Validate files in beforeUpload.
    captureboolean / 'user' / 'environment'—Pass the capture hint to the native file input.
    name / methodstring'file' / 'post'Multipart field name and HTTP method (POST, PUT or PATCH).
    dataobject or (file) => object / Promise<object>—Additional multipart fields.
    headers / withCredentialsobject / boolean— / falseRequest headers and credential handling.
    onPreview / onDownload(file) => void—Override preview/download. Downloads appear only for done files; local images have a built-in preview.
    onRemove(file) => void / boolean / Promise—Return false (or resolve false) to prevent removal. Accepted removal aborts the active request.
    previewFile(file: File or Blob) => PromiseLike<string>—Generate a local thumbnail URL.
    isImageUrl / iconRender(file) => boolean / (file, listType) => ReactNode—Customize image detection and the file/loading icon.
    itemRender(node, file, fileList, actions) => ReactNode—Customize each row with preview, download and remove actions.
    progressUploadListProgressProps—Customize the line progress indicator.
    disabledbooleanTaoProviderDisable selection and removal; preview remains available.
    openFileDialogOnClickbooleantrueOpen the file picker when the trigger is activated.
    hasControlInsidebooleanAutomatic / 自动Set false for plain-text/custom non-interactive children so the wrapper is keyboard accessible.
    onDrop / onFocusevent handler—Receive drop and focus events.
    localeUploadLocaleTaoProviderOverride uploading, preview, download, remove and error labels.
    classNames / stylesobject or ({ props }) => object—Semantic parts: root, trigger, list, item.
    className / rootClassName / stylestring / string / CSSProperties—Root styling. Dragger style configures the drop zone.
    id / childrenstring / ReactNode—Input identifier and trigger content. null or false hides the trigger.

    Upload.Dragger

    Inherits Upload props and adds height?: number for the drop zone, excluding the file list.

    UploadFile

    Requires uid and name. Common fields are status (uploading / done / error / removed), percent, url, thumbUrl, originFileObj, response, error, size and type. Files stopped by beforeUpload have no status.

    ShowUploadListInterface

    showPreviewIcon, showDownloadIcon and showRemoveIcon accept booleans or (file) => boolean. previewIcon, downloadIcon, removeIcon and extra accept ReactNode or (file) => ReactNode. Cards show preview and remove by default; download is opt-in.

    Connect an upload service

    The live examples use local selection or simulated requests. To send files to a server, set action to the upload endpoint and name to the multipart field the server expects.

    import { Upload, Button } from '@rockshin/tao-ui';
    
    // The application must implement this endpoint.
    export function ServerUpload() {
      return (
        <Upload action="/api/uploads" name="file" data={{ folder: 'documents' }}>
          <Button>Upload to server</Button>
        </Upload>
      );
    }

    If you supply customRequest, report progress with onProgress and finish each request once with onSuccess or onError. Return an object with an abort() method if your transport supports cancellation. With a controlled fileList, store the list from onChange to show the latest status for each file.

    Since 0.0.49, Upload also handles failures while resolving action or data, and synchronous exceptions from customRequest. The affected file shows an error and the other files in the batch continue.