Skip to main content

File hooks

These hooks manage file attachments for buildings, sites, and users. Files are fetched via SWR with array-based cache keys, and mutations trigger revalidation of related caches (parent entity, file lists). The hooks are created via a factory pattern (createFileHooks) that accepts an ApiAdapter, with convenience wrappers exported for direct import.

Hooks​

HookDescription
useFilesFetches all files.
useFileFetches a single file by ID, with update mutation.
useFilesByBuildingIdFetches files attached to a building, optionally filtered by tag.
useFilesBySiteIdFetches files attached to a site, optionally filtered by tag.
useUploadFileToBuildingUploads a file and attaches it to a building.
useUploadFileToSiteUploads a file and attaches it to a site.
useUploadFileToUserUploads a file and attaches it to a user.
useDeleteFileDeletes a file and revalidates related caches.
useDownloadFileClient-side file download with blob handling and fallback.

useFiles​

Fetches all files from the API.

Signature​

function useFiles(): { files: DbFile[]; isLoading: boolean; isError: Error | undefined }

Parameters​

None.

Returns​

FieldTypeDescription
filesDbFile[]Array of files, defaults to empty array.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.

Example​

const { files, isLoading } = useFiles();

if (isLoading) return <Skeleton />;
return <FileList files={files} />;

useFile​

Fetches a single file by ID and provides an update mutation.

Signature​

function useFile(id: number | null): UseFileReturn

Parameters​

ParamTypeRequiredDescription
idnumber | nullYesFile ID, or null to skip fetching.

Returns​

FieldTypeDescription
fileDbFile | nullThe fetched file, or null if not found/loading.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.
updateFile(arg: Partial<DbFile>) => Promise<DbFile>Trigger function to update the file.
isMutatingbooleanWhether an update is in progress.
updateErrorError | undefinedError from the update mutation.
updatedDataDbFile | undefinedThe updated file data after mutation.

Example​

const { file, updateFile, isMutating } = useFile(fileId);

const handleRename = async (newName: string) => {
  await updateFile({ name: newName });
};

Notes​

On successful update, revalidates the file cache, files list, and any associated building/site file lists based on the file's attachedFilesBuildingId or attachedFilesSiteId.

useFilesByBuildingId​

Fetches files attached to a specific building.

Signature​

function useFilesByBuildingId(buildingId: number, tag?: string): UseFilesReturn

Parameters​

ParamTypeRequiredDescription
buildingIdnumberYesThe building ID to fetch files for.
tagstringNoOptional tag to filter files.

Returns​

FieldTypeDescription
filesDbFile[]Array of files attached to the building.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.

Example​

const { files, isLoading } = useFilesByBuildingId(building.id, "floorplan");

useFilesBySiteId​

Fetches files attached to a specific site.

Signature​

function useFilesBySiteId(siteId: number, tag?: string): UseFilesReturn

Parameters​

ParamTypeRequiredDescription
siteIdnumberYesThe site ID to fetch files for.
tagstringNoOptional tag to filter files.

Returns​

FieldTypeDescription
filesDbFile[]Array of files attached to the site.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.

Example​

const { files } = useFilesBySiteId(site.id);

useUploadFileToBuilding​

Uploads a file and attaches it to a building.

Signature​

function useUploadFileToBuilding(buildingId: number): UseUploadReturn

Parameters​

ParamTypeRequiredDescription
buildingIdnumberYesThe building ID to attach the file to.

Returns​

FieldTypeDescription
uploadFile(arg: { fileData: Partial<DbFile> }) => Promise<DbFile>Trigger function to upload.
isMutatingbooleanWhether upload is in progress.
uploadErrorError | undefinedError from the upload mutation.
uploadedDataDbFile | undefinedThe uploaded file data.

Example​

const { uploadFile, isMutating } = useUploadFileToBuilding(building.id);

const handleUpload = async (fileData: Partial<DbFile>) => {
  await uploadFile({ fileData });
};

Notes​

On success, revalidates filesByBuilding, files, and the parent building cache keys.

useUploadFileToSite​

Uploads a file and attaches it to a site.

Signature​

function useUploadFileToSite(siteId: number): UseUploadReturn

Parameters​

ParamTypeRequiredDescription
siteIdnumberYesThe site ID to attach the file to.

Returns​

FieldTypeDescription
uploadFile(arg: { fileData: Partial<DbFile> }) => Promise<DbFile>Trigger function to upload.
isMutatingbooleanWhether upload is in progress.
uploadErrorError | undefinedError from the upload mutation.
uploadedDataDbFile | undefinedThe uploaded file data.

Example​

const { uploadFile } = useUploadFileToSite(site.id);
await uploadFile({ fileData: { name: "site-plan.pdf", ...metadata } });

Notes​

On success, revalidates filesBySite, files, and the parent site cache keys.

useUploadFileToUser​

Uploads a file and attaches it to a user.

Signature​

function useUploadFileToUser(userId: number): UseUploadReturn

Parameters​

ParamTypeRequiredDescription
userIdnumberYesThe user ID to attach the file to.

Returns​

FieldTypeDescription
uploadFile(arg: { fileData: Partial<DbFile> }) => Promise<DbFile>Trigger function to upload.
isMutatingbooleanWhether upload is in progress.
uploadErrorError | undefinedError from the upload mutation.
uploadedDataDbFile | undefinedThe uploaded file data.

Example​

const { uploadFile } = useUploadFileToUser(user.id);
await uploadFile({ fileData: { name: "avatar.png" } });

Notes​

On success, revalidates files and the parent user cache keys.

useDeleteFile​

Deletes a file and revalidates related caches.

Signature​

function useDeleteFile(buildingId?: number, siteId?: number): UseDeleteReturn

Parameters​

ParamTypeRequiredDescription
buildingIdnumberNoBuilding ID for cache revalidation.
siteIdnumberNoSite ID for cache revalidation.

Returns​

FieldTypeDescription
deleteFile(fileId: number) => Promise<void>Function to delete a file by ID.
isMutatingbooleanWhether deletion is in progress.
deleteErrorError | undefinedError from the delete mutation.
deletedDataunknownResponse data from deletion.

Example​

const { deleteFile, isMutating } = useDeleteFile(building.id);

const handleDelete = async (fileId: number) => {
  await deleteFile(fileId);
};

Notes​

Revalidates files, the specific file key, and conditionally filesByBuilding/building or filesBySite/site based on provided IDs.

useDownloadFile​

Client-side hook for downloading files. Handles presigned URLs, blob downloads, and fallback to direct links.

Signature​

function useDownloadFile(): UseDownloadReturn

Parameters​

None.

Returns​

FieldTypeDescription
downloadFile(file: any, fileName?: string) => Promise<void>Function to trigger download.
isDownloadingbooleanWhether download is in progress.
downloadErrorError | nullError from the download attempt.

Example​

const { downloadFile, isDownloading } = useDownloadFile();

<Button onClick={() => downloadFile(file)} disabled={isDownloading}>
  Download
</Button>

Notes​

Attempts blob download via fetch for presigned URLs, with automatic fallback to window.open if CORS or fetch fails. Resolves filename from file.name, file.originalFile.name, or file.metadata.name.