TheBuilder.BlurPlaceholder 0.1.2

Blur Placeholder for Umbraco

Generate compact WebP, BlurHash, or ThumbHash image placeholders once in Umbraco and deliver one simple string to your frontend.

Blur Placeholder is an Umbraco CMS 17 package that adds a generated, read-only blurPlaceholder property to the default Image media type. The value is generated when the image is saved and stored with the media item, so frontend requests do no image processing.

Output formats

The property always contains one self-describing string, never a JSON envelope. Native values use blurhash: or thumbhash: so consumers never have to guess which decoder to use.

Install

Blur Placeholder supports Umbraco CMS 17.1 and later. Add it to the Umbraco web project:

dotnet add package TheBuilder.BlurPlaceholder

The package registers its services and backoffice extension automatically. On first startup it installs the string data type and adds blurPlaceholder to the default Image media type.

Configure

Configuration is read from the BlurPlaceholder section in appsettings.json. All settings below show their defaults, so the section can be omitted when the default tiny WebP output is appropriate.

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

Settings reference

Invalid values fail application startup with the relevant configuration key and accepted range. Settings that affect generated bytes participate in the backfill fingerprint, so an output change allows one new pass over existing images instead of creating a recurring media-library scan.

Verify the installation

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, representation, dimensions, and stored string.

When an image has not yet been saved, the property explains that its placeholder will be generated on save. Generation failures are logged and transient failures are retried without blocking the media save.

Delivery API

Enable the Delivery API and its media endpoints in the host application's appsettings.json:

{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": true,
        "Media": {
          "Enabled": true,
          "PublicAccess": true
        }
      }
    }
  }
}

Request blurPlaceholder explicitly to keep the additional payload opt-in:

GET /umbraco/delivery/api/v2/media/item/{mediaId}?expand=properties[$all]&fields=properties[blurPlaceholder]

The response includes the generated string in the media item's properties object:

{
  "path": "/station-platform.png/",
  "createDate": "2026-08-10T08:46:31.004237Z",
  "updateDate": "2026-08-10T08:46:31.004237Z",
  "id": "d55605e1-c63a-42cd-86a6-a99adca2a565",
  "name": "station-platform.png",
  "mediaType": "Image",
  "url": "/media/n1hbay0t/station-platform.png",
  "extension": "png",
  "width": 1536,
  "height": 1024,
  "bytes": 2468341,
  "properties": {
    "blurPlaceholder": "data:image/webp;base64,UklGRoIAAABXRUJQVlA4IHYAAABwAwCdASoQAAsALoVCoVClJSUlBQCESzgE6AxZblsod8ldbAAA/vs0YnnRmszUoA9/XeE6xi8oqvuYhNTIbmf34VbF388vudNZmZ7B4pF4N5Kwiixxuf2/w1XnA/yuEyJteMig85jSjuP1fcG9JRe+aOBYEAAA"
  },
  "focalPoint": {
    "left": 0.5,
    "top": 0.5
  },
  "crops": []
}

With the default configuration, blurPlaceholder is ready to pass to an image component as a blur data URL. Native BlurHash and ThumbHash values can instead be decoded on the application server; see the Delivery API guide for Next.js and Nuxt server-component examples.

Documentation

• Quickstart: install, configure, and verify the package.
• Delivery API: request and consume the property, including native-hash decoding.
• Operations: backfills, retries, logging, and health checks.
• License and attribution: package licensing and bundled third-party implementation notices.

The runnable sample host is available in samples/TheBuilder.BlurPlaceholder.Example.