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

Usage

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

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.