optiq-image / react
react
optiq-image/react — React hook around compressImage. Requires React 18+ (optional peer dependency).
Interfaces
UseOptiqOptions
Extends
Omit<CompressCallOptions,"signal"|"onProgress">
Properties
| Property | Type | Description | Inherited from |
|---|---|---|---|
allowFormatConversion? | boolean | Default true when targetFormat is auto. When false, the output keeps the input format. | CompressCallOptions.allowFormatConversion |
allowLossyResize? | boolean | Explicitly permit resizing in lossless mode (the result is then no longer pixel-identical to the input). | CompressCallOptions.allowLossyResize |
autoFormats? | OutputFormat[] | Formats considered when targetFormat is auto. Default: jpeg, png, webp, avif. Remove avif if your audience includes browsers without AVIF decoding or encode time matters most. | CompressCallOptions.autoFormats |
compressor? | Compressor | Use a specific compressor (worker pool) instead of the shared one. | - |
enabled? | boolean | Set to false to keep the hook idle. Default true. | - |
markOutput? | boolean | Mark lossy JPEG/WebP outputs with a small comment/chunk (~20 bytes) so a later run recognises them and does not re-encode them again (each lossy pass is checked against its own input, so repeated passes compound the loss). Default false in the library; the CLI enables it. AVIF and lossless outputs are not marked. | CompressCallOptions.markOutput |
maxCandidates? | number | Maximum number of encodes (candidates) per image. Defaults: visually-lossless 18, balanced 10, lossless 4. | CompressCallOptions.maxCandidates |
maxInputBytes? | number | Reject inputs larger than this many bytes before reading them. Default 100 MiB. | CompressCallOptions.maxInputBytes |
maxInputPixels? | number | Reject inputs whose header declares more pixels than this (decompression-bomb guard). Default 50 MP. | CompressCallOptions.maxInputPixels |
maxOutputBytes? | number | Upper bound for output size. Not a promise: reported in unmetConstraints if impossible. | CompressCallOptions.maxOutputBytes |
maxWidthOrHeight? | number | Downscale so that the longest side is at most this. Never applied in lossless mode unless allowLossyResize. | CompressCallOptions.maxWidthOrHeight |
minQuality? | number | Minimum SSIM (0..1) for perceptual modes. Defaults: visually-lossless 0.99, balanced 0.975. Ignored in lossless mode. | CompressCallOptions.minQuality |
minSavingsRatio? | number | Return the original when the best candidate saves less than this fraction. Default 0.02. | CompressCallOptions.minSavingsRatio |
mode? | CompressionMode | Default balanced. | CompressCallOptions.mode |
onUnmetConstraints? | "best-effort" | "throw" | What to do when no candidate meets all constraints. Default best-effort (result lists unmetConstraints). | CompressCallOptions.onUnmetConstraints |
preserveAnimation? | boolean | Default true. When false, animated inputs may be flattened to their first frame (with a warning). | CompressCallOptions.preserveAnimation |
preserveMetadata? | boolean | Keep EXIF/XMP and non-sRGB/sRGB ICC profiles. Default true. Setting false strips them (privacy: removes GPS etc). | CompressCallOptions.preserveMetadata |
reoptimize? | boolean | Re-encode inputs that carry the Optiq marker anyway. Default false: in perceptual modes a marked input is only optimised at container level (metadata), unless it is resized or converted to an explicitly requested format. | CompressCallOptions.reoptimize |
searchStrategy? | SearchStrategy | binary (default) searches quality per codec; fixed encodes each codec once at a preset quality. | CompressCallOptions.searchStrategy |
targetFormat? | TargetFormat | Default auto. | CompressCallOptions.targetFormat |
UseOptiqState
Properties
| Property | Type | Description |
|---|---|---|
cancel | () => void | Abort the running compression (terminates its worker). |
error? | unknown | The thrown value; usually an OptiqError with a code. The original file is always still usable. |
progress? | ProgressEvent | - |
result? | CompressionResult | - |
status | UseOptiqStatus | - |
Type Aliases
UseOptiqStatus
ts
type UseOptiqStatus = "idle" | "compressing" | "done" | "error" | "cancelled";Functions
useOptiq()
ts
function useOptiq(file, options?): UseOptiqState;Compress file whenever it (or the options) change. Cancels the previous run automatically, and on unmount.
tsx
const { status, result, progress, cancel } = useOptiq(file, { mode: "balanced" });Parameters
| Parameter | Type |
|---|---|
file | Blob | null | undefined |
options? | UseOptiqOptions |