@eazip/react

Reference for the React hook, task state, tray props, provider config, localization, and re-exported Core types.

npm install @eazip/react

Requires React and React DOM 18 or later.

`useEazip()`

import { useEazip } from '@eazip/react';

const zip = useEazip();

Returned members

Member	Description
`download(options)`	Starts a task and returns its ID immediately.
`task`	Current task or `null`.
`tasks`	Current task as an array; currently contains at most one item.
`isBusy`	`true` while the current task is processing.
`cancel(taskId?)`	Aborts and removes the matching or current task.
`retry(taskId?)`	Restarts a retained request.
`dismiss(taskId?)`	Removes the matching or current task.
`downloadZip(taskId, zipIndex)`	Downloads one completed ZIP part.
`downloadAll(taskId?)`	Downloads every completed ZIP part.

Local download options

Option	Default	Description
`files`	required	`ZipInput` files, blobs, URLs, or source objects.
`strategy`	`'local'`	Local execution.
`zipName`	`'download.zip'`	Output filename.
`compressionLevel`	`6`	Deflate level from `0` through `9`.
`concurrency`	`4`	Parallel Local URL fetches.
`onProgress`	—	Receives Local progress.

Shared download options

Option	Default	Description
`failOnUrlError`	`false`	Fail instead of returning partial output.
`maxZipSizeBytes`	—	Best-effort output part size.
`signal`	—	External abort signal.
`fetch`	global `fetch`	Custom source or Cloud requests.
`onChange`	—	Receives underlying Core snapshots.
`autoDownload`	provider value or `true`	Downloads the first output automatically.

Cloud download options

Frontend-created sessions add:

Option	Default	Description
`strategy`	required `'cloud'`	Cloud execution.
`publicKey`	provider value or required	Browser-safe public key.
`files`	required	Remote URL sources.
`apiBaseUrl`	provider or SDK default	Cloud API origin.
`mode`	`'stream'`	`stream` or `stored`.
`turnstileToken` / `onChallenge`	—	Anti-abuse challenge handling.
`polling`	SDK defaults	Cloud polling controls.

Backend-created sessions use createSession(context) and optional filesTotal instead of files, publicKey, and challenge options.

`EazipTask`

Field	Description
`id`	Task identifier.
`state`	`processing`, `completed`, `partial`, `failed`, or `expired`.
`strategy`	Local or Cloud.
`zipName`	Requested or resolved archive name.
`filesTotal`	Known input count.
`progress`	Local progress or `null`.
`zips`	Output ZIP metadata and download state.
`skippedCount` / `skipped`	Omitted source count and Local details.
`error`	Serializable fatal error.
`downloadStarted`	Whether an automatic or manual output download started.
`createdAt` / `expiresAt`	Client creation time and optional Cloud expiry.
`canRetry`	Whether the original request can be replayed.

`<EazipTray />`

import { EazipTray } from '@eazip/react';

<EazipTray />

Props

Prop	Default	Description
`placement`	`'corner'`	`corner`, `bar`, or `anchored`.
`theme`	`'auto'`	`light`, `dark`, or system preference.
`accent`	`'#3056d3'`	CSS accent color.
`autoDownload`	store value	Overrides automatic-download behavior.
`autoHideMs`	`20000`	Completed auto-downloaded task delay; `0` disables.
`locale`	`'en'`	Built-in `en` or `ja` catalog.
`messages`	—	Partial message overrides.
`className`	—	Class on the tray root.
`zIndex`	`9999`	Tray stacking order.
`offset`	—	`{ x?, y? }` CSS-pixel placement offset.
`container`	`document.body`	Portal target.
`onStateChange`	—	Called on task identity or lifecycle-state changes.

`<EazipProvider />`

The provider is optional. Its config supplies shared fallbacks and isolated store state.

<EazipProvider
  config={{
    strategy: 'cloud',
    publicKey: 'pk_ez_...',
    defaults: { zipName: 'export.zip' },
  }}
>
  <App />
</EazipProvider>

Config	Description
`strategy`	Default Local or Cloud strategy.
`publicKey` / `apiBaseUrl`	Shared Cloud connection defaults.
`defaults`	ZIP name, compression, mode, failure, and splitting defaults.
`autoDownload`	Shared automatic-download default.
`persist`	Enables resumable Cloud task persistence; defaults to `true`.
`storageKey`	Overrides the persistence key.

Options passed directly to download() take precedence.

The package exports en, ja, EazipTrayLocale, and EazipTrayMessages for tray localization. It also re-exports Core error classes and shared types used by the React API, including ZipInput, ZipJob, and progress and output types.