Skip to content

Files you choose

Open a file that the person chooses, or save one file.

Files you choose lets a page that is on the screen open a file that the person chooses in the system panel, and save one file where the person chooses. The system panel is the question. The page gets only the file that the person chooses. A file is saved only at the place that the person chooses. The page never gets a path.

Declare files.choose in the manifest actions of the app. Without it, Access shows no row, the file field does not open, and files.save returns unauthorized. Access shows one row, Files you choose, under This computer. The levels are Off and Allow, and the default is Allow. The row has no Ask level, because the system panel is the question. The app can keep or send a file with its other permissions, for example to the agent or by email.

Open a file

Use a normal file field. No SDK call is needed.

const input = document.createElement('input');
input.type = 'file';
input.addEventListener('change', async () => {
  const text = await input.files[0].text();
  // Use the text.
});

At Allow, the system panel opens when the person clicks the field. On the iPhone, iOS shows its own menu: Photo Library, Take Photo and Choose File. "Take Photo" uses the camera text of the iPhone app.

At Off, the file field does not open. A click, input.click() and input.showPicker() do nothing (showPicker() throws NotAllowedError), and a file that the person drops on the page is not given to the page. The title bar shows "Files you choose is off for this app." with a link to Access. A page that is not on the screen gets the same result as Off. Redac also removes showOpenFilePicker, showSaveFilePicker and showDirectoryPicker from the page. Use the file field and files.save.

Save one file

files.save({name, content, encoding, mimeType?}) returns {saved}.

ArgumentRule
name1 to 255 characters. No /, no \, no NUL character. Not . and not ... It is the default name.
contentThe file text or bytes.
encodingutf8 (at most 1,048,576 bytes as UTF-8) or base64 (at most 1,398,104 characters, 1 MiB of bytes).
mimeTypeOptional. At most 255 characters. It is a hint only.

The system save panel opens with name as the default name. The person chooses the place. The result is {saved: true} after the write, and {saved: false} when the person cancels. The path is never returned. A second call from the same page while a panel is open returns unavailable. A name or content that is not valid returns invalid_args. A write that fails returns unavailable. At Off, the call returns unauthorized.

const result = await client.cap.call('files.save', {
  name: 'report.csv',
  content: 'name,total\nTea,3\n',
  encoding: 'utf8',
  mimeType: 'text/csv',
});
if (!result.saved) {
  // The person cancelled. Do not show an error.
}

Only a page on the screen can save. A function cannot use files.save. On the iPhone, the phone answers the call itself and shows "Save to Files". A phone page uses the same Access level that the desktop shows.

Downloads

A page cannot download a file. A link with download, a blob link and a navigation to a file are blocked on both devices. Use files.save.

Limits

A page can change state in its own realm. A page that gets around the file guard still gets only the file that the person picks in the system panel. The guard protects the Off choice, not the file.

Synced from the Redac Desktop developer guide on 2026-11-16 · SDK contract version 28