---
title: "FilterOptions"
canonical_url: https://docs.zvid.io/docs/structure/properties/filter-options/
source: docs/structure/properties/filter-options.md
content_revision: 6338386a1dd87e4a
---

# FilterOptions

`filter` adjusts visual appearance before the element is composed.

```typescript
interface FilterOptions {
  brightness?: number;
  contrast?: number;
  saturate?: number;
  "hue-rotate"?: string;
  blur?: number | string;
  invert?: boolean | number;
  colorTint?: string;
}
```

| Property     | Range/format             | Notes                                                                     |
| ------------ | ------------------------ | ------------------------------------------------------------------------- |
| `brightness` | number, `-100` to `100`  | Lower or raise brightness.                                                |
| `contrast`   | number, `-100` to `100`  | Lower or raise contrast.                                                  |
| `saturate`   | number, `-100` to `100`  | Lower or raise saturation.                                                |
| `hue-rotate` | degree string            | Prefer `"30deg"`; legacy numeric strings such as `"30"` remain accepted.  |
| `blur`       | number, `0` to `100`     | Unitless amount; numeric strings are accepted for backward compatibility. |
| `invert`     | boolean or number `0..1` | `true` fully inverts; a number applies partial inversion.                 |
| `colorTint`  | `#rgb` or `#rrggbb`      | Multiplies the red, green, and blue channels.                             |

`blur` is not a CSS length. Values such as `"4px"` are not supported.

Brightness, contrast, and saturation use `0` for an unchanged image. Positive
contrast increases gradually: `1` is a small adjustment, `25` maps to a contrast
factor of `1.5`, `50` to `2`, and `100` to `3`. Negative contrast reduces that
factor toward `0` at `-100`. Saturation uses the same factor range; brightness
instead adds or subtracts lightness.

Blur increases linearly relative to the image or video's shortest side, so the
same setting scales with the element's dimensions. Invert blends RGB colors
continuously from `0` (unchanged) to `1` (fully inverted), including when combined
with brightness, contrast, saturation, or hue adjustments. Tint `#ffffff` leaves
the RGB channels unchanged.

## Example

This is a property fragment to merge into an `IMAGE`, `VIDEO`, `GIF`, or
legacy `SVG` visual. It is not a complete project or a CSS filter string.

```json
{
  "filter": {
    "brightness": -10,
    "hue-rotate": "30deg",
    "blur": 20,
    "invert": 0.25
  }
}
```

## Used By

- [Image Elements](https://docs.zvid.io/docs/structure/image-elements/)
- [Video Elements](https://docs.zvid.io/docs/structure/video-elements/)
- [GIF Elements](https://docs.zvid.io/docs/structure/gif-elements/)
- [SVG Elements (deprecated)](https://docs.zvid.io/docs/structure/svg-elements/)

For [HTML elements](https://docs.zvid.io/docs/structure/text-elements/), use the CSS `filter` property through
[`customCode`](https://docs.zvid.io/docs/structure/text-elements/#native-css--javascript-customcode) instead of
the `filter` object.


```json
{
  "name": "docs-img-filters",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#0b0d12",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
      "x": 15,
      "y": 90,
      "width": 450,
      "height": 300
    },
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
      "x": 495,
      "y": 90,
      "width": 450,
      "height": 300,
      "filter": {
        "brightness": 8,
        "contrast": 12,
        "saturate": 25
      }
    },
    {
      "type": "TEXT",
      "text": "original",
      "x": 240,
      "y": 440,
      "anchor": "center-center",
      "style": {
        "fontSize": 28,
        "color": "#ffffff",
        "fontFamily": "Poppins"
      }
    },
    {
      "type": "TEXT",
      "text": "filter applied",
      "x": 720,
      "y": 440,
      "anchor": "center-center",
      "style": {
        "fontSize": 28,
        "color": "#a78bfa",
        "fontFamily": "Poppins"
      }
    }
  ]
}
```

Recorded comparison fixture: original vs. brightness + contrast + saturation

[Watch rendered example](https://cdn.zvid.io/library/docs/img-filters.mp4)