Quickstart

Install and verify the extension in an Umbraco CMS 17 project.

Install

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

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.

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.

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

Quickstart

Install

Configure

Verify

Settings reference