---
title: Quickstart
description: Install and verify the extension in an Umbraco CMS 17 project.
seo:
  image: /og/quickstart.png
---

## Install

Install the package into an Umbraco CMS 17.1 or later project:

```bash
dotnet add package TheBuilder.BlurPlaceholder
```

The extension was created with the official Umbraco extension template flow. For a local package build, add a project reference to `src/TheBuilder.BlurPlaceholder` instead.

## Configure

Add the section below to `appsettings.json`, then restart the application. The first startup installs the string data type and adds the property to the default Image media type. Existing images are processed once when `BackfillExisting` is enabled.

```json
{
  "BlurPlaceholder": {
    "Enabled": true,
    "Algorithm": "Webp",
    "DecodeToDataUrl": true,
    "BackfillExisting": true,
    "RetryInterval": "12:00:00",
    "Webp": { "MaximumDimension": 16, "Quality": 60 },
    "BlurHash": { "MaximumDimension": 32, "ComponentsX": 4, "ComponentsY": 3 },
    "ThumbHash": { "MaximumDimension": 100 },
    "DecodedDataUrl": { "WebpQuality": 60 }
  }
}
```

These are also the defaults, so the entire section can be omitted when tiny WebP output is appropriate.

## Verify

Upload or replace an Image media item. The read-only `blurPlaceholder` field should show a preview in the media workspace. The persisted value is a plain string and can be copied without any JSON envelope.

## Settings reference

| Setting | Default | Purpose |
| --- | --- | --- |
| `Enabled` | `true` | Enables save-time generation and maintenance. Disabling it preserves existing values. |
| `Algorithm` | `Webp` | Selects `Webp`, `BlurHash`, or `ThumbHash`. |
| `DecodeToDataUrl` | `true` | Converts native hashes to browser-ready WebP data URLs. WebP output is always a data URL. |
| `BackfillExisting` | `true` | Runs one existing-image pass for each output-settings fingerprint. |
| `RetryInterval` | `12:00:00` | Controls maintenance scans for missing placeholders and transient-failure retries; minimum one minute. |
| `Webp.MaximumDimension` | `16` | Longest edge of direct WebP output; valid range 16–64. |
| `Webp.Quality` | `60` | Direct lossy WebP quality; valid range 1–100. |
| `BlurHash.MaximumDimension` | `32` | Longest input edge passed to BlurHash; valid range 16–100. |
| `BlurHash.ComponentsX/Y` | `4` / `3` | BlurHash detail grid; each axis accepts 1–9. |
| `ThumbHash.MaximumDimension` | `100` | Longest input edge passed to ThumbHash; valid range 1–100. |
| `DecodedDataUrl.WebpQuality` | `60` | WebP quality after decoding BlurHash or ThumbHash; valid range 1–100. |

Invalid values fail application startup with the relevant configuration key and accepted range. Settings that change generated bytes participate in the fingerprint, so changing them permits one new backfill instead of creating a recurring media-library scan.