Skip to main content

Overview

Uploads a file to Sublay storage without any server-side processing. The raw file is stored and a proxy URL is returned. Use this for PDFs, videos, Office documents, or any file type where you don’t need variant generation. For images that need resizing or format conversion, use useUploadImage instead.
Requires an authenticated user. The hook uses the private axios instance and will throw if no session is active.

Usage Example

Parameters

uploadFile(file, pathParts, options?) accepts three arguments:
file
BrowserFile | RNFile
required
The file to upload. In the browser, pass a standard File object. In React Native, pass { uri, name, type? }.
pathParts
string[]
required
Storage path segments. The file is stored under the joined path, with a UUID sub-folder appended automatically for uniqueness. For example, ["documents", "user-123"] stores the file at documents/user-123/<uuid>/<filename>.
options
UploadFileOptions
Optional associations and metadata.

Options

entityId
string
Associates the file with an entity. The file is deleted when the entity is deleted.
commentId
string
Associates the file with a comment. The file is deleted when the comment is deleted.
spaceId
string
Associates the file with a space.
position
number
Display order when a record has multiple attachments. Defaults to 0.
metadata
Record<string, any>
Custom key-value data stored alongside the file record.

Returns

The hook returns the uploadFile function directly (no state wrappers). The function returns a Promise<UploadResponse>:
The type field is inferred automatically from the file’s MIME type. PDFs and Office documents become "document", video files become "video", images become "image", and everything else becomes "other".