use-file-dialog

Open the native file picker without rendering an input.


Package	`@vizejs/composable/use-file-dialog`
Own the source	`vize lib pull composable:use-file-dialog`
Runtime exports	`useFileDialog`
Gzip budget	2048 B

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useFileDialog } from "@vizejs/composable/use-file-dialog";

Try it

Pick a file with your own button

Open the native file picker from any control and read the selected files.

Open the interactive example

What to observe: Choose a CSV file opens the picker; the output shows the chosen file's name and size. Clear removes it.

accept, multiple and capture can be refs, and open() accepts overrides. onCancel reports a closed picker.

Compare the initial and interacted states

Pick a file with your own button: initial state — Initial state

Pick a file with your own button: state after the verified interactions — After the verified interactions

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useFileDialog } from "@vizejs/composable/use-file-dialog";

const { files, open, reset } = useFileDialog({ accept: ".csv,text/csv", multiple: false });
</script>

<template>
  <div class="composable-example">
    <p>Open the file picker from your own button and show the chosen file.</p>
    <div class="example-actions">
      <button type="button" @click="() => open()">Choose a CSV file</button>
      <button type="button" :disabled="!files" @click="() => reset()">Clear</button>
    </div>
    <output aria-live="polite">{{
      files?.[0] ? `Selected ${files[0].name} (${files[0].size} bytes)` : "No file selected."
    }}</output>
  </div>
</template>

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useFileDialog`	system	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useFileDialog`

Open the native file picker without rendering an input. A detached <input type="file"> is created lazily on the first open (never during setup or server rendering), configured from reactive options plus per-call overrides, and observed for change and cancel. The selection is exposed as a readonly File[]. Listeners are removed when the owning reactive scope stops. Server rendering: files is initialFiles and open returns false.

function useFileDialog(options: UseFileDialogOptions = {}): FileDialogControls

const { files, open, onChange } = useFileDialog({ accept: "image/*" });
onChange((selection) => upload(selection));

Types

`FileInputLike`

Minimal <input type="file"> consumed by useFileDialog.

Member	Type	Description
`type`	`string`	Input type; set to `"file"`.
`accept`	`string`	Accepted MIME types / extensions.
`multiple`	`boolean`	Allow selecting multiple files.
`files`	`ArrayLike<File> \| null`	Selected files.
`value`	`string`	Serialized value; cleared to reset the selection.
`click`	`() => void`	Open the native dialog.
`setAttribute`	`(name: string, value: string) => void`	Set an attribute (`capture`, `webkitdirectory`).
`removeAttribute`	`(name: string) => void`	Remove an attribute.

`FileDialogHost`

Document capability used to create the hidden input.

Member	Type	Description
`createElement`	`(tagName: "input") => FileInputLike`	Create an `<input>` element.

`FileDialogSettings`

Per-dialog settings accepted by useFileDialog and open.

Member	Type	Description
`accept`?	`string`	Accepted MIME types / extensions, for example `"image/*,.pdf"`.
`multiple`?	`boolean`	Allow selecting multiple files.
`capture`?	`FileDialogCapture`	Capture from a camera on supporting devices.
`directory`?	`boolean`	Select a directory (`webkitdirectory`).
`reset`?	`boolean`	Clear the current selection before the dialog opens.

`UseFileDialogOptions`

Options for useFileDialog.

Member	Type	Description
`accept`?	`MaybeRefOrGetter<string>`	Accepted MIME types / extensions.
`multiple`?	`MaybeRefOrGetter<boolean>`	Allow selecting multiple files.
`capture`?	`MaybeRefOrGetter<FileDialogCapture \| undefined>`	Capture from a camera on supporting devices.
`directory`?	`MaybeRefOrGetter<boolean>`	Select a directory instead of files.
`reset`?	`boolean`	Clear the current selection whenever the dialog opens.
`initialFiles`?	`readonly File[] \| null`	Selection before the dialog was used.
`host`?	`MaybeRefOrGetter<FileDialogHost \| null \| undefined>`	Document capability for alternate runtimes and tests.

`FileDialogControls`

Reactive state and actions returned by useFileDialog.

Member	Type	Description
`files`	`Readonly<ShallowRef<readonly File[] \| null>>`	Current selection; `null` before any selection or after `reset`.
`open`	`(overrides?: FileDialogSettings) => boolean`	Open the native dialog. Browsers require a user gesture.
`reset`	`() => void`	Clear the selection.
`onChange`	`(handler: (files: readonly File[] \| null) => void) => () => void`	Observe selections.
`onCancel`	`(handler: () => void) => () => void`	Observe dialogs dismissed without a selection.