nb-input-file

File picker component for Vue.js 3+. It uses a native <input type="file"> (visually hidden) plus a themed control. Validation covers accept, extensions, size, duplicates, and optional GIF dimension / video metadata rules. The component emits File[] for previews or uploads in the parent.

Installation

yarn add @vlalg-nimbus/nb-inputs

npm install @vlalg-nimbus/nb-inputs

Usage

import { createApp } from 'vue'
import App from './App.vue'

import NbInputComponents from '@vlalg-nimbus/nb-inputs'
import "@vlalg-nimbus/nb-inputs/dist/style.css";

const app = createApp(App)
app.use(NbInputComponents)
app.mount('#app')

import NbInputComponents from '@vlalg-nimbus/nb-inputs'
import "@vlalg-nimbus/nb-inputs/dist/style.css";

export default defineNuxtPlugin(context => {
  context.vueApp.use(NbInputComponents)
})

To use, simply call the component, in this case it will be NbInputFile or nb-input-file.

<template>
  <NbInputFile />
</template>

<template>
  <nb-input-file />
</template>

<template>
  <nb-input-file></nb-input-file>
</template>

Preview & Playground

Select the component you want to edit/test.

Props

(*) = required.

Prop names below use camelCase in script; in templates use the usual kebab-case equivalents (e.g. input-name for inputName).

Identity, layout, and accessibility

File input behaviour

Message block

Label

Icon area

Main control typography and colors (light theme)

Main control colors (dark theme)

Message block typography

File list typography

Constraints line typography

Clear action typography

Counter typography

Slots

Events

Validation failures are not rendered inside NbInputFile. Listen to validation-errors (and optionally validation-error) in the parent and show messages there (list, toast, form summary, etc.).

Choosing validation-error vs validation-errors

Both carry the same shape per entry: { file, fileName, msg, errorType }. The difference is how often they fire and what you should do in the parent.

validation-errors (recommended for “what failed?” in the UI)

• Emits one array after the component finishes processing a picker selection (merge + validation for that change event).
• If the user picks three invalid files, you get one emission whose array has three items — easy to assign to a single ref / state field.
• Also emits [] when errors are cleared (removed a file from the list, clear-all, etc.), so the parent stays in sync without guessing.
• Use this for: an error list under the field, a summary alert, form-level validation state, or anything that should always mirror “the current set of validation messages” in one place.

validation-error (recommended for “something bad happened” reactions)

• Emits separately for each rejected item (same example: three bad files → three events, one payload each).
• The parent does not receive a [] “clear” signal from this event when errors are wiped; clearing is only reflected on validation-errors.
• Use this for: toast per failure, analytics one event per failed file, focusing a specific row, or logging — anything tied to individual failures rather than replacing a full list.

Practical rule: bind validation-errors → fieldErrors = list for display. Optionally also listen to validation-error → showToast(payload.msg) if you want instant feedback per file. You rarely need to only use validation-error and manually merge into an array unless you have custom queueing logic.

Error types (errorType)

Stable string on each validation payload (validation-error / entries inside validation-errors):

Locale keys

The locale prop is one object. Use it to override any of the following keys. Placeholders in templates use braces, e.g. {fileName} — they are substituted at runtime. Pass only the keys you need; any key you omit keeps the default English template in the right-hand column exactly as implemented in the component.

Validation message templates

These strings are shown when a file fails validation or when counters / limits apply.

Component UI strings

These strings are used for the constraints line, clear control, visible control aria-label, and related copy.

Example:

<NbInputFile
  :locale="{
    filesCounter: '{current} of {max}',
    sizeExceeded: 'File \'{fileName}\' is too large.',
    clearAction: 'Remove all'
  }"
/>

Behaviour notes

• Opening the picker: click the wrapper, the visible control (role="button"), or the label (handled separately). Keyboard: Tab focuses the visible control; Enter/Space opens the dialog when hasTabIndexEnter is true. The native input covers the hit area with opacity 0. Keyboard focus may use :focus-visible so the label floats without breaking mouse clicks.
• changed / current-value: emitted after validation and merge; invalid files do not enter the internal list (errors go to errors and validation events).
• Clearing errors: a new picker run clears then re-validates; removing a file or using clear-all clears errors and emits validation-errors with [].
• GIF / video: async validation in the browser; large files may add delay.
• Remove in list: index-based; same file name with different size is treated as different files.

Example: errors in the parent

Show errors in the template from one reactive list, and optionally toast each failure:

<script setup>
import { ref } from 'vue'

const fieldErrors = ref([])

function onValidationErrors(list) {
  fieldErrors.value = Array.isArray(list) ? [...list] : []
}

function onValidationError(payload) {
  // Optional: one toast per bad file (does not replace fieldErrors)
  console.warn(payload.msg, payload.errorType, payload.fileName)
}
</script>

<template>
  <NbInputFile
    nb-id="pick"
    input-name="pick"
    @validation-errors="onValidationErrors"
    @validation-error="onValidationError"
  />
  <ul v-if="fieldErrors.length">
    <li v-for="(err, i) in fieldErrors" :key="i">
      {{ err.msg }} ({{ err.errorType }})
    </li>
  </ul>
</template>

Example: typical field

nbId and inputName are required. Listen to @changed or @current-value for the current File[] (there is no v-model).

<script setup>
import { ref } from 'vue'

const files = ref([])

function onFilesChanged(list) {
  files.value = Array.isArray(list) ? [...list] : []
}
</script>

<template>
  <NbInputFile
    nb-id="attachment"
    input-name="attachment"
    file-extension=".pdf,image/*"
    multiple
    :max-files="5"
    show-file-list
    show-constraints-text
    @changed="onFilesChanged"
  />
</template>

When the file field sits in a row with other controls and you do not want the constraints / message / file list to grow the row height, set extra-contend-absolute (kebab-case in templates):

<NbInputFile
  nb-id="attachment"
  input-name="attachment"
  show-file-list
  extra-contend-absolute
  @changed="onFilesChanged"
/>

Example: using File[] in the UI (complete)

File from @changed lives in memory. For inline preview in HTML/CSS, build a blob URL: URL.createObjectURL(file), then point src, srcset, href, or background-image at that string. Always URL.revokeObjectURL(url) when the file leaves the list or on unmount, or memory is not released.

Where blob URLs are commonly used

For very small files, FileReader.readAsDataURL is an alternative to object URLs (handy for data-URL-only APIs); it is less ideal for large video/PDF because the string is huge.

The example below uses @changed, revokes URLs on change/unmount, previews image / video / audio / PDF, offers a download link for any file, shows CSS background for the first image, and uploads with FormData.

<script setup>
import { ref, watch, onBeforeUnmount, computed } from 'vue'

const files = ref([])

/** One row per selected file: blob URL + metadata for templates */
const previews = ref([])

function fileKind(file) {
  const t = file.type || ''
  if (t.startsWith('image/')) return 'image'
  if (t.startsWith('video/')) return 'video'
  if (t.startsWith('audio/')) return 'audio'
  if (t === 'application/pdf' || /\.pdf$/i.test(file.name)) return 'pdf'
  return 'file'
}

function revokeAll() {
  previews.value.forEach((p) => URL.revokeObjectURL(p.url))
  previews.value = []
}

watch(
  files,
  (list) => {
    revokeAll()
    if (!list?.length) return
    previews.value = list.map((f) => ({
      url: URL.createObjectURL(f),
      name: f.name,
      type: f.type,
      kind: fileKind(f)
    }))
  },
  { deep: true }
)

onBeforeUnmount(revokeAll)

function onFilesChanged(list) {
  files.value = Array.isArray(list) ? [...list] : []
}

const firstImageUrl = computed(() => previews.value.find((p) => p.kind === 'image')?.url ?? '')

function openInNewTab(url) {
  window.open(url, '_blank', 'noopener,noreferrer')
}

async function uploadAll(endpoint) {
  const fd = new FormData()
  files.value.forEach((f, i) => fd.append(`file_${i}`, f, f.name))
  const res = await fetch(endpoint, { method: 'POST', body: fd })
  return res.ok
}
</script>

<template>
  <NbInputFile
    nb-id="media-pack"
    input-name="media-pack"
    file-extension="image/*,video/*,audio/*,.pdf"
    multiple
    show-file-list
    @changed="onFilesChanged"
  />

  <section v-if="previews.length" class="previews">
    <!-- CSS: background-image (first image only, example) -->
    <div
      v-if="firstImageUrl"
      class="hero-thumb"
      :style="{ backgroundImage: `url(${firstImageUrl})` }"
      role="img"
      :aria-label="'Cover: first image'"
    />

    <template v-for="p in previews" :key="p.url">
      <!-- Images: <picture> gives optional <source type="…">; <img> alone is fine too -->
      <picture v-if="p.kind === 'image'">
        <source :srcset="p.url" :type="p.type" />
        <img :src="p.url" :alt="p.name" width="100" height="100" style="object-fit: cover" />
      </picture>

      <video v-else-if="p.kind === 'video'" controls width="320" :src="p.url" />

      <audio v-else-if="p.kind === 'audio'" controls :src="p.url" />

      <!-- PDF: iframe works in many browsers; add sandbox if you must limit embedded content -->
      <iframe
        v-else-if="p.kind === 'pdf'"
        :title="p.name"
        width="100%"
        height="360"
        :src="p.url"
      />

      <!-- Other types: download link + open in new tab -->
      <p v-else>
        <a :href="p.url" :download="p.name">{{ p.name }}</a>
        <button type="button" @click="openInNewTab(p.url)">Open in new tab</button>
      </p>
    </template>
  </section>

  <!-- Upload: send File objects, not blob: strings -->
  <button type="button" :disabled="!files.length" @click="uploadAll('/api/upload')">
    Upload (example)
  </button>
</template>

<style scoped>
.hero-thumb {
  width: 200px;
  height: 120px;
  background-size: cover;
  background-position: center;
  border-radius: 8px;
  margin-bottom: 8px;
}
</style>

If you do not need <source>, a single <img :src="p.url"> for kind === 'image' is enough.

Canvas sketch (createImageBitmap avoids an intermediate object URL for drawing):

const bmp = await createImageBitmap(file)
ctx.drawImage(bmp, 0, 0)
bmp.close()

Limitations

• No built-in drag-and-drop or HTTP upload; use File[] from @changed with your own upload logic.
• Treat errorType values documented above as the stable contract for branching in your app; they are the strings emitted on validation payloads.