useFileUpload Hook

The useFileUpload hook manages file uploads for a custom chat interface. It uploads each selected file, validates it, and exposes the validated file record that you pass to submitQuery.

The hook must be used inside a KapaProvider. The provider handles the upload and validation requests, including CAPTCHA verification.

Usage

import { useState } from "react";
import { useChat, useFileUpload } from "@kapaai/react-sdk";

function ChatComposer() {
  const [query, setQuery] = useState("");
  const { submitQuery, isGeneratingAnswer } = useChat();
  const {
    files,
    addFiles,
    removeFile,
    clearFiles,
    isAnyUploading,
    validatedFiles,
    maxFiles,
  } = useFileUpload();

  function handleFileChange(event) {
    addFiles(Array.from(event.target.files ?? []));

    // Allow the user to select the same file again after removing it.
    event.target.value = "";
  }

  function handleSubmit(event) {
    event.preventDefault();
    if (!query.trim() || isAnyUploading) return;

    submitQuery(
      query,
      validatedFiles.map((file) => file.file_upload),
    );
    setQuery("");
    clearFiles();
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="file"
        multiple
        onChange={handleFileChange}
        disabled={files.length >= maxFiles}
      />

      <ul>
        {files.map((file) => (
          <li key={file.tempId}>
            {file.file.name}: {file.status}
            <button type="button" onClick={() => removeFile(file.tempId)}>
              Remove
            </button>
          </li>
        ))}
      </ul>

      <input
        value={query}
        onChange={(event) => setQuery(event.target.value)}
        placeholder="Ask a question"
      />
      <button type="submit" disabled={isGeneratingAnswer || isAnyUploading}>
        Send
      </button>
    </form>
  );
}

Wait until isAnyUploading is false before submitting. Pass only the file_upload records from validatedFiles to submitQuery. Files with an unsupported or error status are not included in validatedFiles.

Return values

Property	Type	Description
files	FileItem[]	All selected files and their current upload status.
addFiles	(files: File[]) => void	Adds files to the upload queue. Files beyond maxFiles are ignored.
removeFile	(tempId: string) => void	Removes a file and cancels its upload if one is in progress.
clearFiles	() => void	Removes all files and cancels uploads in progress.
isAnyUploading	boolean	true while any file is uploading or being validated.
validatedFiles	ValidatedFileItem[]	Files accepted by server-side validation and ready for submitQuery.
maxFiles	number	Maximum number of files that can be selected for one question.

File states

Each item in files has a status property:

Status	Description
queued	Waiting for the upload to start.
uploading	Uploading to storage.
uploaded	Uploaded and waiting for validation.
validating	Being checked by the server.
validated	Accepted and ready to attach to a question.
unsupported	Rejected because the file type is not supported.
error	Upload or validation failed.

Use these states to show progress and errors in your interface. File limits and supported file types are enforced by the backend.

Limits and supported formats

Limit	Value
Files per question	10
Files per conversation	No separate limit. Each question in the conversation can include up to 10 files.
Size per file	100 MB
Text file content	60,000 UTF-8 characters

Each uploaded file can be attached to one question only and must be submitted within 15 minutes of uploading.

Supported formats are determined by the file name extension:

Category	Supported extensions
PDF	.pdf
Images	.png, .jpg, .jpeg
Text and data	.csv, .txt, .ini, .log, .json, .md, .mdx, .rtf, .toml, .xml, .xsd, .yaml, .yml, .tsv, .ndjson, .jsonl
Web	.html, .js, .jsx, .ts, .tsx, .css, .scss, .less
Programming languages	.py, .java, .kt, .swift, .c, .h, .cpp, .hpp, .cc, .go, .rs, .rb, .php, .r, .jl, .m, .sql
Shell scripts	.sh, .bash, .zsh, .fish, .bat, .ps1
Documentation and markup	.tex, .bib, .rst, .adoc, .org
Configuration and build files	.properties, .cfg, .conf, .editorconfig, .gitattributes, .gitignore, .dockerfile, .dockerignore, .makefile, .cmake, .ninja, .proto, .graphql, .gql
Geospatial and semantic data	.xsl, .xslt, .kml, .gpx, .rdf, .ttl, .n3

Files named Dockerfile and Makefile are also supported. Text, code, configuration, and markup files must use UTF-8 encoding.