> 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.

# Upload

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

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.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      multiple
      beforeUpload={() => false}
      defaultFileList={[
        { uid: '1', name: 'project-brief.pdf', status: 'done' },
        { uid: '2', name: 'requirements.docx', status: 'done' },
        {
          uid: '3',
          name: 'budget.xlsx',
          status: 'error',
          error: new Error('Example: the server rejected this file'),
        },
      ]}
    >
      <Button>Select files</Button>
    </Upload>
  );
}
```

### Controlled file list
Own fileList through onChange; the clear button updates the same state.
```tsx preview
import { Upload, Button, Stack, type UploadFile } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [files, setFiles] = useState<UploadFile[]>([]);
  return (
    <Stack gap="md">
      <Upload
        fileList={files}
        beforeUpload={() => false}
        onChange={(info) => setFiles(info.fileList)}
      >
        <Button>Select files</Button>
      </Upload>
      <Button variant="secondary" onClick={() => setFiles([])}>
        Clear list
      </Button>
    </Stack>
  );
}
```

### Validate and ignore files
LIST\_IGNORE excludes rejected files from the list. Browser accept is only a selection hint.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [error, setError] = useState('');
  return (
    <div>
      <Upload
        accept="image/*"
        beforeUpload={(file) => {
          if (!file.type.startsWith('image/')) {
            setError('Choose an image file.');
            return Upload.LIST_IGNORE;
          }
          setError('');
          return false;
        }}
      >
        <Button>Select image</Button>
      </Upload>
      <p role="status">{error}</p>
    </div>
  );
}
```

### Multiple files and limits
maxCount caps the list length; one replaces the current file.
```tsx preview
import { Upload, Button, Stack } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Stack gap="md">
      <Upload multiple maxCount={3} beforeUpload={() => false}>
        <Button>Select up to three files</Button>
      </Upload>
      <Upload maxCount={1} beforeUpload={() => false}>
        <Button variant="secondary">Replace single file</Button>
      </Upload>
    </Stack>
  );
}
```

### Drag and drop
Click anywhere in the drop zone or drop multiple files. Files stay local; no request is sent.
```tsx preview
import { Upload } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload.Dragger
      multiple
      beforeUpload={() => false}
      height={200}
      hasControlInside={false}
    >
      <svg
        width="48"
        height="48"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        strokeWidth="1.5"
        aria-hidden="true"
        style={{ color: 'var(--tao-primary)' }}
      >
        <path d="M12 16V3m-5 5 5-5 5 5M4 16v5h16v-5" />
      </svg>
      <strong>Click or drag files to this area</strong>
      <span style={{ color: 'var(--tao-color-text-secondary)' }}>
        Select a single file or multiple documents.
      </span>
    </Upload.Dragger>
  );
}
```

### Picture list
A compact list with thumbnails, filenames and actions. Click a thumbnail to preview; new images stay local.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      listType="picture"
      accept="image/*"
      multiple
      beforeUpload={() => false}
      defaultFileList={[
        {
          uid: '1',
          name: 'image-01.png',
          status: 'done',
          url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
        },
        {
          uid: '2',
          name: 'image-02.png',
          status: 'error',
          url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
          error: new Error('Example upload error'),
        },
      ]}
    >
      <Button>Select images</Button>
    </Upload>
  );
}
```

### 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.
```tsx preview
import { Upload, Modal, type UploadFile } from '@rockshin/tao-ui';
import { useState } from 'react';
const imageUrl =
  'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png';
export default function Demo() {
  const [files, setFiles] = useState<UploadFile[]>([
    { uid: '1', name: 'image-01.png', status: 'done', url: imageUrl },
    { uid: '2', name: 'image-02.png', status: 'done', url: imageUrl },
    { uid: '3', name: 'image-03.png', status: 'uploading', percent: 48 },
    {
      uid: '4',
      name: 'image-04.png',
      status: 'error',
      error: new Error('Example upload error'),
    },
  ]);
  const [preview, setPreview] = useState({ name: '', url: '' });
  const [error, setError] = useState('');
  const showPreview = (file: UploadFile) => {
    setError('');
    if (file.url || file.thumbUrl) {
      setPreview({ name: file.name, url: file.url || file.thumbUrl! });
    } else if (file.originFileObj) {
      const reader = new FileReader();
      reader.onload = () =>
        setPreview({ name: file.name, url: String(reader.result) });
      reader.onerror = () => setError('Could not read this image.');
      reader.readAsDataURL(file.originFileObj);
    }
  };
  return (
    <>
      <Upload
        listType="picture-card"
        hasControlInside={false}
        accept="image/*"
        multiple
        maxCount={6}
        fileList={files}
        beforeUpload={() => false}
        onChange={({ fileList }) => setFiles(fileList)}
        onPreview={showPreview}
        showUploadList={{
          showPreviewIcon: (file) =>
            !!(file.url || file.thumbUrl || file.originFileObj),
        }}
      >
        {files.length >= 6 ? null : (
          <>
            <svg
              width="20"
              height="20"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              strokeWidth="1.8"
              aria-hidden="true"
            >
              <path d="M12 4v16M4 12h16" />
            </svg>
            <span>Add image</span>
          </>
        )}
      </Upload>
      {error && <p role="alert">{error}</p>}
      <Modal
        open={!!preview.url}
        title={preview.name}
        footer={null}
        onClose={() => setPreview({ name: '', url: '' })}
      >
        <img
          src={preview.url || undefined}
          alt={preview.name}
          style={{ display: 'block', width: '100%' }}
        />
      </Modal>
    </>
  );
}
```

### Circular picture list
The complete tile and its upload trigger are circular. Keyboard focus reveals the same actions as hover.
```tsx preview
import { Upload } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      listType="picture-circle"
      accept="image/*"
      beforeUpload={() => false}
      defaultFileList={[
        {
          uid: '1',
          name: 'profile.png',
          status: 'done',
          url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
        },
      ]}
      hasControlInside={false}
    >
      <svg
        width="20"
        height="20"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        strokeWidth="1.8"
        aria-hidden="true"
      >
        <path d="M12 4v16M4 12h16" />
      </svg>
      <span>Add image</span>
    </Upload>
  );
}
```

### 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.
```tsx preview
import { Upload } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [avatar, setAvatar] = useState('');
  const [error, setError] = useState('');
  return (
    <>
      <Upload
        listType="picture-circle"
        showUploadList={false}
        accept="image/*"
        maxCount={1}
        hasControlInside={false}
        beforeUpload={(file) => {
          if (!file.type.startsWith('image/') || file.size > 2 * 1024 * 1024) {
            setError('Choose an image smaller than 2 MB.');
            return Upload.LIST_IGNORE;
          }
          setError('');
          const reader = new FileReader();
          reader.onload = () => setAvatar(String(reader.result));
          reader.onerror = () => setError('Could not read this image.');
          reader.readAsDataURL(file);
          return false;
        }}
      >
        {avatar ? (
          <img
            src={avatar}
            alt="Selected avatar"
            style={{
              width: '100%',
              height: '100%',
              borderRadius: '50%',
              objectFit: 'cover',
            }}
          />
        ) : (
          <span>Select avatar</span>
        )}
      </Upload>
      {error && <p role="alert">{error}</p>}
    </>
  );
}
```

### 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 preview
import { Upload, Button, Switch, type UploadProps } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [fail, setFail] = useState(false);
  const customRequest: UploadProps['customRequest'] = ({
    onProgress,
    onSuccess,
    onError,
  }) => {
    let percent = 0;
    const timer = window.setInterval(() => {
      percent += 20;
      onProgress?.({ percent });
      if (percent === 100) {
        window.clearInterval(timer);
        if (fail) onError?.(new Error('Simulated upload failure'));
        else onSuccess?.({ simulated: true });
      }
    }, 300);
    return { abort: () => window.clearInterval(timer) };
  };
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <label>
        <Switch checked={fail} onChange={setFail} /> Simulate failure
      </label>
      <Upload
        multiple
        customRequest={customRequest}
        progress={{ showInfo: true }}
      >
        <Button>Start simulated upload</Button>
      </Upload>
    </div>
  );
}
```

### Disabled upload
Disable selection and removal while keeping completed files available for preview.
```tsx preview
import { Upload, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [disabled, setDisabled] = useState(true);
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <label>
        <Switch checked={disabled} onChange={setDisabled} /> Disabled
      </label>
      <Upload
        disabled={disabled}
        listType="picture-card"
        beforeUpload={() => false}
        defaultFileList={[
          {
            uid: '1',
            name: 'image.png',
            status: 'done',
            url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
          },
        ]}
        hasControlInside={false}
      >
        <svg
          width="20"
          height="20"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          strokeWidth="1.8"
          aria-hidden="true"
        >
          <path d="M12 4v16M4 12h16" />
        </svg>
        <span>Add image</span>
      </Upload>
    </div>
  );
}
```

### Confirm removal
onRemove can reject removal synchronously or asynchronously. This example protects files with a switch.
```tsx preview
import { Upload, Button, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [locked, setLocked] = useState(true);
  return (
    <div>
      <label>
        <Switch checked={locked} onChange={setLocked} /> Protect files
      </label>
      <Upload
        beforeUpload={() => false}
        onRemove={() => !locked}
        defaultFileList={[
          { uid: '1', name: 'protected-report.pdf', status: 'done' },
        ]}
      >
        <Button>Select file</Button>
      </Upload>
    </div>
  );
}
```

### Extra list information
Render per-file information and choose which list actions appear.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      beforeUpload={() => false}
      defaultFileList={[
        { uid: '1', name: 'design-notes.pdf', size: 245760, status: 'done' },
      ]}
      showUploadList={{
        extra: (file) => (
          <small>{Math.ceil((file.size ?? 0) / 1024)} KB · local file</small>
        ),
        showDownloadIcon: false,
      }}
    >
      <Button>Select document</Button>
    </Upload>
  );
}
```

### Phone selection and paste
pastable accepts clipboard files. The browser and device control available file sources.
```tsx preview="iframe-follow"
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload pastable multiple beforeUpload={() => false} listType="picture">
      <Button>Select or paste images</Button>
    </Upload>
  );
}
```

## API

| Property                            | Type                                                     | Default         | Description                                                                                                 |
| ----------------------------------- | -------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------- |
| `fileList / defaultFileList`        | `UploadFile[]`                                           | —               | Controlled list / initial uncontrolled list.                                                                |
| `onChange`                          | `({ file, fileList, event? }) => void`                   | —               | Called for selection, progress, completion, failure and removal.                                            |
| `action`                            | `string 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.                                            |
| `showUploadList`                    | `boolean or ShowUploadListInterface`                     | true            | Configure extra content and preview, download and remove actions per file.                                  |
| `maxCount`                          | `number`                                                 | —               | Limit list length; 1 replaces the previous file. Hide the trigger yourself with children={null}.            |
| `multiple / directory / pastable`   | `boolean`                                                | false           | Multiple selection / directory selection / clipboard file upload.                                           |
| `accept`                            | `string or AcceptConfig`                                 | —               | Selection hint, such as image/\*. Validate files in beforeUpload.                                           |
| `capture`                           | `boolean / 'user' / 'environment'`                       | —               | Pass the capture hint to the native file input.                                                             |
| `name / method`                     | `string`                                                 | 'file' / 'post' | Multipart field name and HTTP method (POST, PUT or PATCH).                                                  |
| `data`                              | `object or (file) => object / Promise<object>`           | —               | Additional multipart fields.                                                                                |
| `headers / withCredentials`         | `object / boolean`                                       | — / false       | Request 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.                                               |
| `progress`                          | `UploadListProgressProps`                                | —               | Customize the line progress indicator.                                                                      |
| `disabled`                          | `boolean`                                                | TaoProvider     | Disable selection and removal; preview remains available.                                                   |
| `openFileDialogOnClick`             | `boolean`                                                | true            | Open the file picker when the trigger is activated.                                                         |
| `hasControlInside`                  | `boolean`                                                | Automatic / 自动  | Set false for plain-text/custom non-interactive children so the wrapper is keyboard accessible.             |
| `onDrop / onFocus`                  | `event handler`                                          | —               | Receive drop and focus events.                                                                              |
| `locale`                            | `UploadLocale`                                           | TaoProvider     | Override uploading, preview, download, remove and error labels.                                             |
| `classNames / styles`               | `object or ({ props }) => object`                        | —               | Semantic parts: root, trigger, list, item.                                                                  |
| `className / rootClassName / style` | `string / string / CSSProperties`                        | —               | Root styling. Dragger style configures the drop zone.                                                       |
| `id / children`                     | `string / 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.

```tsx
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](https://rickyshin93.github.io/tao-ui/guide/changelog.md), 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.
