Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

FileUpload

Pick or drop files, see image thumbnails and file details, and preview images and PDFs.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

0 files selectedDrag files here Images and PDFs

Install

Run in your project
bunx --bun @getweini/cli@latest add file-upload

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

0 files selectedDrop files here Images and PDFs
Vue
<script setup lang="ts">
import { ref } from 'vue'
import FileUpload from './components/ui/file-upload/FileUpload.vue'

const files = ref<File[]>([])
const messages = {
  browse: 'Add files',
  drop: 'Drop files here',
  hint: 'Images and PDFs',
  clear: 'Clear',
  selectedCount: (count: number) => `${count} files selected`,
  previewFile: (name: string) => `Preview ${name} (opens in a new tab)`,
  removeFile: (name: string) => `Remove ${name}`,
}
</script>

<template>
  <FileUpload
    v-model="files"
    name="attachments"
    accept="image/*,.pdf"
    multiple
    class="max-w-md"
    :messages="messages"
  />
</template>

The drop zone becomes a local preview when you add a file. Drop more files into the same area or use Add files. When multiple files are selected, click a filename below the preview to switch files. PDFs display inline in browsers with an embedded PDF viewer and can also open in a new tab. The native file input participates in forms. Your application handles uploads and validation messages.

When to use it

Profile image

Accept one image through the picker or drop area.

Case attachments

Collect several PDFs or images and allow removal before submission.

More examples

Avatar image

accept filters picker and drop selection consistently.

Avatar image
<script setup lang="ts">
import { ref } from 'vue'
import FileUpload from './components/ui/file-upload/FileUpload.vue'

const files = ref<File[]>([])
const messages = {
  browse: 'Choose image',
  drop: 'Drop image here',
  clear: 'Clear',
  selectedCount: (count: number) => `${count} selected`,
  removeFile: (name: string) => `Remove ${name}`,
}
</script>
<template>
  <label for="avatar">Profile image</label>
  <FileUpload id="avatar" v-model="files" name="avatar" accept="image/*" :messages="messages" />
</template>

Multiple attachments

The model contains the selected File objects; upload them in your form flow.

Multiple attachments
<script setup lang="ts">
import { ref } from 'vue'
import FileUpload from './components/ui/file-upload/FileUpload.vue'

const files = ref<File[]>([])
const messages = {
  browse: 'Choose attachments',
  drop: 'Drop attachments here',
  clear: 'Clear all',
  selectedCount: (count: number) => `${count} files selected`,
  removeFile: (name: string) => `Remove ${name}`,
}
function reportRejected(rejected: File[]) {
  console.warn('Unsupported files', rejected)
}
</script>
<template>
  <label for="attachments">Attachments</label>
  <FileUpload
    id="attachments"
    v-model="files"
    name="attachments"
    accept="image/*,.pdf"
    multiple
    :messages="messages"
    @reject="reportRejected"
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

FileUpload

Complete API for FileUpload
NameType or signatureDefaultWhat it does
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
acceptpropstring | undefinedNot setLimit the file types that can be chosen.
multiplepropboolean | undefinedNot setAllow more than one item or file to be selected.
capturepropboolean | "user" | "environment" | undefinedNot setSuggest which camera to use when choosing a file on a supported device.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
previewpropboolean | undefinedtrueShow local thumbnails and offer previews for supported files. Defaults to true.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
messagespropFileUploadMessagesRequiredSupply the text this component displays for its built-in actions and states.
modelValuemodelFile[] | undefined[]Current value. Use v-model to keep it in sync with your page.
selectevent[files: File[]]—Emitted when the user selects an item.
update:modelValueevent[value: File[]]—Requests a new model value from the parent.
rejectevent[files: File[]]—Emitted when reject happens.
errorslot{ message: string; messages: string[]; }OptionalContent for the error area of FileUpload.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
openexposed() => void—Open this component from application code.
clearexposed() => void—Access clear from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/file-upload/types.ts
// ------- IMPORTS -------

import type { ControlSize } from '@getweini/vue/types'

// ------- TYPES -------

export interface FileUploadMessages {
  browse: string
  drop: string
  clear: string
  selectedCount: (count: number) => string
  removeFile: (name: string) => string
  /** Optional instructions shown below the drop label. */
  hint?: string
  /** Name for the action that opens an image or PDF in a new tab. */
  previewFile?: (name: string) => string
  /** Override the default compact file size label. */
  fileSize?: (bytes: number) => string
}

export interface FileUploadProps {
  id?: string
  name?: string
  form?: string
  accept?: string
  multiple?: boolean
  capture?: boolean | 'user' | 'environment'
  required?: boolean
  disabled?: boolean
  invalid?: boolean
  /** Show local thumbnails and offer previews for supported files. Defaults to true. */
  preview?: boolean
  size?: ControlSize
  messages: FileUploadMessages
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • The component selects files; your application uploads and handles server errors.
  • Picker and drop paths use the same accept rules; rejected files arrive through reject.
  • Set preview to false to keep file names and sizes without opening local previews.

Accessibility and localization

  • Localize all action and count messages. Connect requirements and errors using aria-describedby.

Source contract and editing guidance