SDKsReact Native

Upload a file

Upload local files independently and obtain remote resource URLs with the OpenIM React Native SDK.

Upload device local files to the OpenIMServer storage backend (such as MinIO or third-party cloud object storage). Upon successful upload, the SDK returns a publicly accessible resource URL, commonly used to update user avatars, configure group avatars, or pre-upload media assets before creating URL-based messages.

const { url } = await OpenIMSDK.uploadFile({
  name: 'avatar.png',
  contentType: 'image/png',
  uuid: 'avatar-upload-20260827',
  cause: 'user-avatar',
  filepath,
});

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Target file name for the upload.
`contentType`	`string`	Yes	MIME type of the file (e.g., `image/png`, `video/mp4`).
`uuid`	`string`	Yes	Unique business identifier for tracking this upload task.
`cause`	`string`	No	Business reason tag (such as `user-avatar` or `group-avatar`).
`filepath`	`string`	Yes	Absolute path to the local file readable within the application sandbox.

Return value

Resolves to an object containing the remote URL: { url: string }.

Use the returned url to update user profiles via Update current user profile.
Or pass it to create URL-based media messages and send them via Send pre-uploaded media messages.

Listen for upload status

When uploading large files, monitor upload progress and completion events:

interface UploadProgressPayload {
  current: number;
  size: number;
}

interface UploadCompletePayload {
  data: {
    fileSize: number;
    streamSize: number;
    storageSize: number;
  };
}

const handleUploadProgress = ({ current, size }: UploadProgressPayload) => {
  // Update upload progress percentage in UI
};

const handleUploadComplete = ({ data }: UploadCompletePayload) => {
  // Handle post-upload completion logic
};

// Register listeners
OpenIMSDK.on(OpenIMEvent.UploadOnProgress, handleUploadProgress);
OpenIMSDK.on(OpenIMEvent.UploadComplete, handleUploadComplete);

// Remove listeners
OpenIMSDK.off(OpenIMEvent.UploadOnProgress, handleUploadProgress);
OpenIMSDK.off(OpenIMEvent.UploadComplete, handleUploadComplete);

Remove these listeners when the component unmounts, the user logs out, or accounts switch.

Was this page helpful?