# vue-upload-component: A Vue 3 File Upload Button With Directory and Chunk Support

> lian-yue/vue-upload-component is a Vue 3 upload component that ships as a single button, with multi-file, directory, drag, chunk and PUT support. Here is how it installs, where it stops, and when a different uploader is the better call.

**lian-yue/vue-upload-component** — Vue.js file upload component, Multi-file upload, Upload directory, Drag upload, Drag the directory, Upload multiple files at the same time, html4 (IE 9), `PUT` method, Customize the filter

- Repository: https://github.com/lian-yue/vue-upload-component
- Stars: 2,687 · Forks: 675
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/lian-yue-vue-upload-component

## What vue-upload-component solves, and who pays the cost

Most file upload widgets try to be a form field. They render a drop zone, a progress bar, a file list, an error area and a retry control, and then you spend an afternoon fighting their CSS. vue-upload-component takes the other position. The README states it plainly: "The component is just a button." Everything visual beyond that is yours to build.

That is the trade. You get a component that handles file selection, drag and drop, directory traversal, concurrency and the actual HTTP transfer, and you give up any prebuilt interface. For a team with an existing design system, that is a good exchange, because the uploader slots into your own markup instead of dragging its own stylesheet along. For a team that wants a finished upload panel in an afternoon, it is the wrong tool, and the missing styles are not a bug you can file.

The intended audience is Vue 3 developers building an internal tool, an admin panel or a product where the upload surface has to match an existing look. The package keywords list vue3 and vue 3, and the peer dependency is vue ^3.5.41, so the current line targets Vue 3 only. Older Vue 2 usage is not described in the README.

## The mechanism: a button that owns selection, queueing and transfer

The repository layout tells you how the project is put together. Source lives in src/, with FileUpload.vue as the main single-file component, and the build produces dist/vue-upload-component.js, dist/vue-upload-component.esm.js and a TypeScript declaration at dist/vue-upload-component.d.ts. The package.json exposes main, module, unpkg and jsdelivr entries, plus a typings field, so the same artifact works through a bundler or straight from a CDN.

Functionally, the README lists the capability set as checkboxes: multi-file upload, upload directory, drag upload, drag the directory, uploading multiple files at the same time, html4 support for IE 9, the PUT method, a customizable filter, thumbnails and chunk upload. Those are the features the component itself owns. The data flow is conventional: the button opens a file picker or receives a drop, the filter decides what is admitted, and the component then sends files, in parallel where the browser allows it, with chunking available for large payloads. What the README does not do is document the prop names, the event names or the chunk size configuration. It points to a hosted documents page instead, and that page is where the actual API surface lives.

Two details are worth flagging. First, the html4 (IE 9) claim sits alongside a Vue 3 peer dependency, which is an odd pairing on its face; treat the IE 9 line as a legacy note inherited from the project's history rather than a supported target for a Vue 3 app. Second, the PUT method option matters if your backend is object storage or a REST endpoint that expects PUT rather than POST, but the README does not say how the method is selected, so confirm that in the docs before you plan around it.

## Installing vue-upload-component and getting one file to a server

The README gives exactly one installation command, and it is the npm one. Run it in your project root, next to your existing Vue 3 app.

```bash
npm install vue-upload-component --save
```

After that, the package resolves through its main and module fields, so a normal import works in a Vite or webpack build. The README does not include a component registration snippet, so the exact import path and prop list have to come from the hosted documents at lian-yue.github.io/vue-upload-component. The repository's own dev script is a webpack dev server, which is how the maintainer runs the demo locally:

```bash
npm run dev
```

That command is for working on the component itself, not for consuming it. If you clone the repository to read the source, the test suite runs through vitest, and the package.json defines the script as:

```bash
npm test
```

For a first real use, the practical path is to start from the demo linked in the README, copy the smallest working example out of the documents page, and point it at your own endpoint. The README does not document the endpoint prop, the request headers, or how a response is interpreted, so budget time for reading the docs page rather than expecting the README to carry you. The component is published with dist and src in its files list, which means you can also read the shipped source directly if the docs leave a question open.

## Where vue-upload-component stops being the right answer

The first limit is documentation depth. The README is a feature checklist, an install line and two links. Prop names, event names, chunk configuration, filter signature and error handling are all deferred to the hosted documents. If your team evaluates libraries by reading the repository, this one will look thinner than it is, and any integration estimate based on the README alone will be wrong.

The second limit is the interface. "The component is just a button" is a design decision, not a gap, but it means accessibility work, progress display, per-file error states and retry logic are yours. A drop zone that announces itself to a screen reader, a progress bar that reflects chunk state, a cancel button: none of that comes in the box. If you need those on a deadline, a component that ships them will be faster.

The third limit is the Vue 3.5.41 floor. The peer dependency is ^3.5.41, so a project pinned to an earlier Vue 3 minor will hit a peer warning on install and will need to upgrade before adopting. The README does not describe a compatibility mode for older Vue 3 releases.

Finally, if your upload needs are one small file behind a form submit, this is more machinery than the job requires. A plain form with an input element and your server's existing multipart handling will be less code and fewer moving parts.

## How it differs from Vue-dropzone and Vuetify's uploader

Vue-dropzone is the comparison most people reach for, and the difference is architectural rather than cosmetic. Dropzone-style components render a complete drop zone with its own markup, styling hooks and file list, so you configure an existing surface. vue-upload-component renders a button and leaves the surface to you. If your design system already defines how a drop area looks, the second approach avoids a styling fight; if you want the drop area to appear by default, the first one saves you the build.

Vuetify's file upload is a different kind of comparison again, because it is not a standalone uploader at all. It is one input inside a broader Material component library, which means adopting it means adopting Vuetify's theming, grid and component conventions. That is a reasonable trade if you are already on Vuetify and a poor one if you are not, since you would be pulling in a whole design system to get one control.

The honest summary: vue-upload-component competes on being small and unopinionated about visuals, and it wins that comparison. It does not compete on out-of-the-box polish, and the README makes no claim that it does.

## Maintenance, upgrade cost and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-22. Releases have come steadily through 2026: v3.2.0 on 2026-08-12, v3.2.1 on 2026-08-25 and v3.2.2 on 2026-09-08. That cadence matters for a component you embed in a build, because it means the published dist artifacts are being regenerated rather than frozen.

The upgrade cost is mostly a Vue version question. Because the peer dependency is ^3.5.41, moving the component forward may require moving Vue forward too, and that is the expensive part of any upgrade here. The build pipeline is dual: rollup produces the ESM and the TypeScript declaration, webpack produces the UMD bundle, and the build-rollup script renames and copies the declaration file into dist and src. If you vendor the source rather than the dist, that naming step is something to understand before you patch anything.

On licensing, the package is Apache-2.0. That is a permissive licence with an explicit patent grant, and it is the same identifier used across the repository. The README also notes that Anthropic supports the project through its Claude for Open Source program. This is a description of what the repository states, not legal advice; if your organisation has a licence review process, run the Apache-2.0 text through it the same way you would for any other dependency.

## Conclusion

Adopt vue-upload-component when you want an upload control that is one button, and you are on Vue 3.5.41 or later, because that is the declared peer dependency. Skip it when you need a full form framework or a UI kit that already bundles an uploader, and skip it if you are still on Vue 2, since the package keywords name vue3 and the peer range starts at 3.5.41. Before wiring it into a release, verify three things yourself: the exact prop names for the chunk options in the hosted documents, how the PUT method is selected, and whether your server accepts the directory upload payload shape. The README does not spell any of those out, so the docs site is the place to check.

## FAQ

### Does vue-upload-component work with Vue 3?

Yes. The package keywords include vue3 and vue 3, and the declared peer dependency is vue ^3.5.41, so the current release line targets Vue 3.5.41 and later.

### How do I install vue-upload-component?

The README gives a single command: npm install vue-upload-component --save. After that the package resolves through its main and module fields for a normal bundler import.

### Does vue-upload-component support drag and drop, directories and chunked uploads?

The README lists drag upload, drag the directory, upload directory and chunk upload as supported features, alongside multi-file upload and uploading multiple files at the same time. Configuration details for those features are in the hosted documents rather than the README.

## Sources

- [Issues](https://github.com/lian-yue/vue-upload-component/issues)
- [lian-yue/vue-upload-component on GitHub](https://github.com/lian-yue/vue-upload-component)
- [License: Apache-2.0](https://github.com/lian-yue/vue-upload-component/blob/master/LICENSE)
- [README](https://github.com/lian-yue/vue-upload-component/blob/master/README.md)
- [Releases](https://github.com/lian-yue/vue-upload-component/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lian-yue-vue-upload-component