---
title: Quickstart
description: Install Blur Placeholder in an Umbraco CMS 17 project, configure the output format, and verify the generated property.
seo:
  image: /og/quickstart.png
---

This is the complete first-time setup path. Stay on this page from installation to a verified placeholder.

## 1. Check the prerequisites

Blur Placeholder supports Umbraco CMS 17.1 through 18.x on .NET 10. Nothing else is required: the package generates placeholders from the media already in your library and needs no external service.

## 2. Install the package

Add the package to the Umbraco web project:

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

The package registers its services and backoffice extension automatically. To work against local source instead, add a project reference to `src/TheBuilder.BlurPlaceholder`.

## 3. Configure the output

The defaults produce a tiny WebP data URL, so you can skip this step entirely and restart the application. To change the output, add the `BlurPlaceholder` section to `appsettings.json`:

```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 }
  }
}
```

Every value above is the default. See the settings reference below for what each one changes.

## 4. Restart the application

The first startup installs the string data type and adds the `blurPlaceholder` property to the default Image media type. With `BackfillExisting` enabled, a background pass then processes the images already in the library.

## 5. Verify the result

Upload or replace an Image media item and save it. The read-only **Blur placeholder** property appears after the standard image fields and shows the generated preview, its representation, and its stored size. The value is a plain string you can copy straight out of the backoffice.

If the property is missing or empty, see [Operations](/operations) for the migration, health-check, and retry behavior behind it.

## 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` | Sets how often maintenance scans for missing placeholders and retries transient failures. Minimum one minute. |
| `Webp.MaximumDimension` | `16` | Longest edge of direct WebP output. Accepts 16 to 64. |
| `Webp.Quality` | `60` | Direct lossy WebP quality. Accepts 1 to 100. |
| `BlurHash.MaximumDimension` | `32` | Longest input edge passed to BlurHash. Accepts 16 to 100. |
| `BlurHash.ComponentsX/Y` | `4` / `3` | BlurHash detail grid. Each axis accepts 1 to 9. |
| `ThumbHash.MaximumDimension` | `100` | Longest input edge passed to ThumbHash. Accepts 1 to 100. |
| `DecodedDataUrl.WebpQuality` | `60` | WebP quality after decoding BlurHash or ThumbHash. Accepts 1 to 100. |

An invalid value fails application startup and names the configuration key and its accepted range.

Settings that change the generated bytes feed the backfill fingerprint. Changing one permits a single new pass over existing images rather than starting a recurring media-library scan.

## Next steps

- [Delivery API](/delivery-api): request the property and render it in Next.js or Nuxt.
- [Overview](/overview): compare the output formats and their measured payloads.
- [Operations](/operations): backfills, retries, schema ownership, and troubleshooting.