vue-file-input

Advanced Vue.js file input with Drag and Drop support.

Mostly for personal use.

---

Example 1

<template>
  <FileInput :state="state"/>
</template>

<script setup>
import {FileInput, getStateInstance} from "@alttiri/vue-file-input";

const state = getStateInstance({recursive: true});
globalThis.state = state;
</script>

// @ts-ignore
globalThis.state = state;

It's just for example. Use getStateInstance in a shared state file.

Example 2

<template>
  <FileInput :state="state" :global-drop-zone="true">
    <FileInputSelectedInfo :state="state"/>
  </FileInput>
  <hr>
  <div class="files">
    <div>Files:</div>
    <div v-for="e of state.fileEntries.value">{{e.name}} — {{formatFileSizeWinLike(e.size)}}</div>
  </div>
</template>
<script setup>
  import {getStateInstance, FileInput, FileInputSelectedInfo} from "@alttiri/vue-file-input";
  import {formatFileSizeWinLike} from "@alttiri/util-js";

  const state = getStateInstance({recursive: true, debug: true});
</script>

See the more advanced demos are online here: https://alttiri.github.io/vue-file-input/

---

FileInput

It's the main component.

Props are:

• state (FileInputState) — the state object from getStateInstance associated with the file input.
• globalDropZone? (boolean | null) — [null (true)] — allows to drop files not only on the input.
• dropZoneSelector? (string | null) — [null] — allows to limit the global drop zone by the selected element.
• accept? (string) — ["*/*"] — types of the accepted files, like "video/*,image/*".
• multiple? (boolean) — [true] — allows to accept multiple files in the system file selector
• nwdirectory? (boolean) — [false] — specify the system file selector to select a folder, NW.js only.

It has 2 slots:

• default — for the content inside the FileInput element.
• modal — the modal which is shown on file drag over.

FileInputDefaultHoverModal

It's default content of modal slot of FileInput element. It just adds a black shadow in the screen bottom.

FileInputDefault

It's default content of default slot of FileInput element.

It has 3 slots:

• hover — it's active when a file is dragging over a drop zone,
• selected — it's active when a file is selected,
• prompt — it's active when where is no file selected.

FileInputDefaultText

It's default content of prompt and selected slots of FileInputDefault element.

It just displays Select file prompt text, or the file count text like 1 file. It also displays Parsing... while processing a lot of dropped files.

FileInputDefaultHoverText

It's default content of hover slots of FileInputDefault element.

It just displays a text prompt like Drop 3 files.

FileInputSelectedInfo

An alternative component for default slot of FileInput element.

Displays the information about the (first) selected/dropped file, for example:

[twitter] SpaceX—2024.01.17—1747633689276608977—GEDXkT3WUAAWxF3.jpg
1.12 MB
2024.01.17 14:55:15

Types

The main function to get state with all data is:

• function getStateInstance(opts?: StateOpts): FileInputState;

// file-input-state.d.ts //

type StateOpts = {
  /** Enable listing files from subfolders. `false` by default. */
  recursive?: boolean;
  /** Enable debug console log. `false` by default. */
  debug?: boolean;
};

export type FileInputState = {
  /** `Ref` of Readonly list of `WebFileEntry` items. */
  fileEntries: Ref<Readonly<WebFileEntry[]>>;
  /** Clear file selecting. */
  clearInput(): void;
  /** Things for advanced use. */
  private: FileInputStatePrivate;
};

export type FileInputStatePrivate = {
  inputElem: Ref<HTMLFileInputElement | null>;
  fileEntries: Ref<WebFileEntry[]>;
  file: ComputedRef<WebFileEntry>;
  count: ComputedRef<number>;
  dropHover: Ref<boolean>;
  dropHoverItemCount: Ref<number>;
  dropHoverTypes: Ref<string[]>;
  parsing: Ref<boolean>;
  setDataTransferHover(dt: DataTransfer | null): void;
  resetDataTransferHover(): void;
  setDataTransfer(dt: DataTransfer | null): void;
  setFiles(filelist: FileList, resetDataTransfer?: boolean): void;
  isNwDirectory: Ref<boolean>; // for NW.js development
};

/** Type for `input` element with exactly `[type="file"]`. */
export interface HTMLFileInputElement extends HTMLInputElement {
  files: FileList; // Since `HTMLInputElement` has `FileList | null`
}

// WebFileEntry.d.ts //

export type WebFileEntryType = "file" | "folder";

export interface FileWithPath extends File {
  readonly path?: string;
}

export declare class WebFileEntry {
  /** A usual `File` object.
   *
   * In NW.js `File` also has `path` property. */
  readonly file: FileWithPath | File;
  /** Just `"file"` or `"folder"`. Not MIME type. */
  readonly type: WebFileEntryType;
  readonly parent: WebFileEntry | undefined;
  get nativePath(): string | undefined;
  get name(): string;
  get children(): Readonly<WebFileEntry[]> | undefined;
  /** Note: the folder size is computed on the creation step. */
  get size(): number;
  get mtime(): number;
  get path(): WebFileEntry[];
  [Symbol.iterator](): Generator<WebFileEntry>;
  flat(): WebFileEntry[];
  static flat(entries: readonly WebFileEntry[]): WebFileEntry[];
  static fromDataTransfer(dt: DataTransfer, recursive: boolean, debug?: boolean): Promise<WebFileEntry[]>;
  static fromFiles(files: File[], type?: WebFileEntryType): WebFileEntry[];
}

---

Installation

From NPM

npm install @alttiri/vue-file-input

From GitHub repository

npm install git+https://github.com/alttiri/vue-file-input.git

More ways

From GitHub repository (a specific version):

• Based on SemVer:

  npm install git+https://github.com/alttiri/vue-file-input.git#semver:1.3.0

  Or add

  "@alttiri/vue-file-input": "github:alttiri/vue-file-input#semver:1.3.0"
  

  as dependencies in package.json file.

  See available tags.

• Based on a commit hash:

  npm install git+https://git@github.com/alttiri/vue-file-input.git#c69898556be0b92bee92b0b96249e5731a2fbf47

  Or add

  "@alttiri/vue-file-input": "github:alttiri/vue-file-input#c69898556be0b92bee92b0b96249e5731a2fbf47"
  

  as dependencies in package.json file.

  See available commits hashes.

From GitHub Packages:

To install you need first to create .npmrc file with @alttiri:registry=https://npm.pkg.github.com content:

echo @alttiri:registry=https://npm.pkg.github.com >> .npmrc

only then run

npm install @alttiri/vue-file-input

Note, that GitHub Packages requires to have also ~/.npmrc file (.npmrc in your home dir) with //npm.pkg.github.com/:_authToken=TOKEN content, where TOKEN is a token with the read:packages permission, take it here https://github.com/settings/tokens/new.