API reference

Create a new SMB client instance. Each instance has its own connection pool and transfer store.

import { SMB } from '@cetapod/react-native-smb';

const smb = SMB();

Connect to server only — no share mounted. Use before listShares() or connectShare().

Param	Type	Description
`url`	string	Server URL without share path
`creds`	SmbCredentials	Username and password

await smb.initialize('smb://192.168.1.100', creds).result();
const shares = await smb.listShares().result();

Authenticate and mount the share from the URL in one step.

const info = await smb
  .connect('smb://nas.local/Media', creds)
  .result();

console.log(info.server, info.share, info.isConnected);

Switch to a different share on an already-initialized server.

await smb.initialize('smb://nas.local', creds).result();
const info = await smb.connectShare('Documents').result();

Close the SMB session and release all pool slots.

await smb.disconnect().result();

Enumerate available shares on the server. Requires prior initialize().

const shares = await smb.listShares().result();
shares.forEach((s) => console.log(s.name, s.comment));

Synchronous state checks — no task required.

if (smb.isConnected()) {
  // safe to browse files
}
if (smb.isInitialized()) {
  // server session exists, may not have share
}

List directory contents. maxDepth: -1 for unlimited recursion. Shallow lists use interactive slot; recursive uses metadata slot.

Param	Type	Default	Description
`path`	string	—	Directory path
`recursive`	boolean	false	Include subdirectories
`maxDepth`	number	-1	Max recursion depth (-1 = unlimited)

const entries = await smb
  .listDirectory('/Photos', false)
  .result();

const tree = await smb
  .listDirectory('/', true, 3)
  .result();

Get metadata for a single file or directory.

const info = await smb.getPathInfo('/document.pdf').result();
console.log(info.size, info.modifiedAt);

Download a remote file to a local path. Use .subscribe() for progress.

const task = smb.downloadFile(
  '/video.mp4',
  `${FileSystem.documentDirectory}video.mp4`,
);
task.subscribe((s) => console.log(s.progress, s.bytesPerSecond));
await task.result();

Upload a local file to a remote SMB path.

const task = smb.uploadFile(
  '/local/photo.jpg',
  '/Photos/photo.jpg',
);
await task.result();

Create a directory. Creates parent directories as needed.

await smb.createDirectory('/Projects/2026/Q1').result();

Delete a file or directory. Directories are removed recursively.

await smb.deleteItem('/old-backup').result();

Rename in place. newName is the basename only, not a full path.

await smb.renameItem('/draft.txt', 'final.txt').result();

Move a file or directory to a new path.

await smb.moveItem('/inbox/file.pdf', '/archive/file.pdf').result();

Copy a file or directory. Set recursive: true for directories.

await smb.copyItem('/templates', '/backup/templates', true).result();

Duplicate a file or folder in place. Returns the new path.

const newPath = await smb.duplicateItem('/report.pdf').result();
// "/report copy.pdf"

Read Windows ACL / security descriptor for a path.

const sd = await smb.getSecurityDescriptor('/shared').result();
sd.dacl.aces.forEach((ace) => console.log(ace.sid, ace.mask));

Snapshot of all connection pool slots. See Architecture.

const info = smb.getPoolInfo();
info.slots.forEach((s) => console.log(s.index, s.state, s.kind));

Subscribe to live pool state changes. Returns a listener ID for unsubscribe.

const id = smb.subscribePoolInfo((snap) => {
  console.log(snap.slots);
});
smb.unsubscribePoolInfo(id);

resetPool() disconnects all slots. dispose() tears down the transfer store — call on logout.

smb.resetPool();
smb.dispose();

React binding for SmbTask.subscribe(). Subscribes automatically on mount and whenever task changes; unsubscribes on unmount / task change.

Returns	Type	Description
`subscribe`	function	Attach an extra listener on top of the automatic subscription; returns unsubscribe
`cancel`	function	Abort the task
`progress`	number	Latest progress 0–1
`status`	TaskStatus	Latest status
`snapshot`	SmbTaskState \| null	Full state object
`task`	SmbTask \| null	Original task ref

Power a transfer tray UI — all active download/upload/copy tasks in one array.

useTransferActions	Description
`clearCompleted()`	Remove finished transfers from tray
`hide(taskId)`	Hide a specific transfer

const transfers = useTransfers(smb);
const { clearCompleted, hide } = useTransferActions(smb);

Function	Description
`normalizePath(path)`	Forward slashes, trim trailing `/`
`splitPath(path)`	Returns `PathComponents`
`joinPath(dir, name)`	Combine directory and filename
`getParentPath(path)`	Parent directory
`getFileName(path)`	Filename from full path

import { splitPath, joinPath, normalizePath } from '@cetapod/react-native-smb';

const { parentDirectory, extension } = splitPath('/docs/report.pdf');
const path = joinPath(parentDirectory, 'archive.pdf');

Function	Description
`generateCopyName(base, ext, existing)`	`"file copy 2.pdf"` naming
`formatFileSize(bytes)`	`"1.5 MB"` human-readable
`formatDate(timestamp)`	Locale date/time from Unix seconds

formatFileSize(1536000);  // "1.46 MB"
formatDate(file.modifiedAt);

Function	Input	Returns
`statusLabel`	`TaskStatus`	`"running"`, `"success"`, etc.
`operationLabel`	`SmbOperatorKind`	`"Download"`, `"List directory"`, etc.
`isTransferKind`	`SmbOperatorKind`	Download, upload, copy, duplicate
`isDeterminateKind`	`SmbOperatorKind`	Same as transfer kinds
`isTerminalStatus`	`TaskStatus`	Success, error, or cancelled

Overview

Connection

File system

Pool & lifecycle

Hooks

Utilities

Label helpers