Quickstart

Install Blur Placeholder in an Umbraco CMS 17 project, configure the output format, and verify the generated property.

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:

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:

{
  "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.

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 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: request the property and render it in Next.js or Nuxt.
Overview: compare the output formats and their measured payloads.
Operations: backfills, retries, schema ownership, and troubleshooting.