# Filters API

> createFilterWorker options, the FilterWorker it returns, apply options for progress and cancel, and the step-by-step filter pipeline.

Source: https://fabricjs-document-engine.jscrate.dev/docs/api/filters-api
Last updated: 2026-10-02

How the worker runs filters, and which browsers use it, is in the [image filters](https://fabricjs-document-engine.jscrate.dev/docs/guides/image-filters) guide.

```ts
import {
  canRunInWorker,
  createFilterWorker,
  runFilterPipeline,
} from "fabricjs-document-engine/filters";
```

## createFilterWorker options

```ts
function createFilterWorker(options?: FilterWorkerOptions): FilterWorker
```

Runs Fabric image filters in a Web Worker, with progress, cancel and newest-run-wins.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `createWorker` | `() => Worker` | `the shipped worker` | Makes a worker, for bundlers that need their own worker setup. |
| `worker` | `boolean` | `true` | `false` runs filters in steps on the main thread instead. |
| `poolSize` | `number` | `1` | Workers to run at once. |
| `bandRows` | `number` | `64` | Rows per step for pixel filters. |
| `engine` | `DocumentEngine` | `none` | Records each finished run as one undo step and drops runs that finish after another document opened. |

## FilterWorker

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `apply` (required) | `(image: FabricImage, filters?: ImageFilter[], options?: ApplyFilterOptions): Promise<boolean>` | — | Applies filters to an image. Resolves `true` when it changed, `false` when a newer run replaced it. Rejects with the signal's reason when aborted. |
| `mode` (required) | `"worker" \| "main-thread"` | — | `worker` or `main-thread`. |
| `terminate` (required) | `(): void` | — | Stops the workers. Runs still going resolve `false`. |

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `signal` | `AbortSignal` | `none` | Cancels the run; the image is left as it was. |
| `onProgress` | `(done: number) => void` | `none` | Called with the share done, from 0 to 1. |

## The pipeline

`runFilterPipeline` is what the worker runs. It also works on the main thread with any `ImageData`, for your own tools.

```ts
function runFilterPipeline(filters: readonly PipelineFilter[], state: PipelineState, options?: PipelineOptions): Promise<ImageData | undefined>
```

Runs filters on `ImageData` in steps, with progress and cancel.

```ts
function canRunInWorker(filters: ReadonlyArray<{
  type?: unknown;
  subFilters?: unknown[];
}>): boolean
```

True when every filter, inside `Composed` ones too, can run in a worker.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bandRows` | `number` | `64` | Rows per step for pixel filters. |
| `onProgress` | `(done: number) => void` | `none` | Called after each step with the share done. |
| `isCancelled` | `() => boolean` | `none` | Checked after each step; `true` stops the run. |
| `pause` | `() => Promise<void>` | `none` | Lets other work run between steps. |

`PIXEL_FILTERS` and `WORKER_FILTERS` list the filter types run in bands of rows, and every type a worker can run. Any other filter makes `apply` use Fabric's `applyFilters`, whatever the createFilterWorker options say.