use-file-system-access

Open, edit, and save local files with the File System Access API.

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 { useFileSystemAccess } from "@vizejs/composable/use-file-system-access";

Try it

Edit a local file in place

Open a text file from disk, edit it and save it back to the same file.

Open the interactive example

What to observe: Open file shows the picker where the API exists; after editing, Save writes to the same file without a download.

dataType selects text, ArrayBuffer or Blob data. saveAs() writes to a new file. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

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 { useFileSystemAccess } from "@vizejs/composable/use-file-system-access";
import { useMounted } from "@vizejs/composable/use-mounted";

const mounted = useMounted();
const { supported, data, fileName, open, save } = useFileSystemAccess({
  dataType: "text",
  types: [{ description: "Text files", accept: { "text/plain": [".txt", ".md"] } }],
});
</script>

<template>
  <div class="composable-example">
    <p>Open a local text file, edit it, and save it back in place.</p>
    <div class="example-actions">
      <button type="button" :disabled="!mounted || !supported" @click="() => open()">
        Open file
      </button>
      <button type="button" :disabled="!fileName" @click="() => save()">Save</button>
    </div>
    <label v-if="fileName">
      {{ fileName }}
      <textarea v-model="data" rows="3"></textarea>
    </label>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? fileName
            ? `Editing ${fileName}`
            : "No file open."
          : "The File System Access API is not available; use a download instead."
    }}</output>
  </div>
</template>

Runtime contract

API

useFileSystemAccess

Open, edit, and save local files with the File System Access API. data is typed by dataType (string, ArrayBuffer, or Blob) and is writable: edit it and call save to write back through the retained file handle. Every action resolves to a discriminated FileSystemAccessResult; a dismissed picker is "cancelled". No listeners or timers are held, so nothing needs cleanup. Server rendering: supported is false, data is undefined, and every action resolves to "unsupported".

function useFileSystemAccess( options?: UseFileSystemAccessOptions<"text">, ): FileSystemAccessControls<"text">

const editor = useFileSystemAccess({ types: [{ accept: { "text/markdown": [".md"] } }] });
await editor.open();
editor.data.value += "\n";
await editor.save();

useFileSystemAccess

function useFileSystemAccess<Kind extends FileSystemAccessDataType>( options: UseFileSystemAccessOptions<Kind> & { readonly dataType: Kind }, ): FileSystemAccessControls<Kind>

useFileSystemAccess

function useFileSystemAccess( options: UseFileSystemAccessOptions<FileSystemAccessDataType> = {}, ): FileSystemAccessControls<FileSystemAccessDataType>

Types

FileSystemAccessDataMap

Value types produced for each FileSystemAccessDataType.

FilePickerAcceptTypeLike

One accepted file type group for the pickers.

FileSystemWritableLike

Writable stream returned by createWritable.

FileSystemFileHandleLike

Minimal FileSystemFileHandle.

OpenFilePickerOptionsLike

Options passed to showOpenFilePicker.

SaveFilePickerOptionsLike

Options passed to showSaveFilePicker.

FileSystemAccessHost

File System Access pickers (window.showOpenFilePicker and friends).

UseFileSystemAccessOptions

Options for useFileSystemAccess.

FileSystemAccessControls

Reactive state and actions returned by useFileSystemAccess.