Blurhash and Directus: How to Add Blurred Image Loading

Blurhash is a compact text-based representation of an image that enables you to display an appealing blurred preview before the original fully loads. This technology not only makes the interface feel more responsive but also provides a more visually engaging waiting experience. Blurhash is an impressive and forward-looking development that offers new possibilities for web and mobile applications.

Implementing Blurhash in Directus has become extremely straightforward thanks to specialized plugins. Whether you're using Next.js, Flutter, or any other framework, the result will be equally compelling. Below, we'll walk through how to integrate this into your project.

Why Use the directus-extension-blurhasher Plugin?

directus-extension-blurhasher automatically generates a Blurhash for images upon upload and stores it in the database. You can choose a detail level (Low, Medium, High), which affects both the length of the Blurhash string and processing speed. The plugin also provides an option for full regeneration: on the next Directus restart, it recalculates the Blurhash for all previously uploaded images. Thanks to automatic migration upon installation, integration is virtually instantaneous.

Installing the Plugin

Through Docker

If you use Docker, add the following snippet to your Dockerfile:

FROM directus/directus:10.10.4

USER root
RUN corepack enable
USER node

RUN pnpm install directus-extension-blurhasher

If you have a Directus fork, just add the dependency:

npm install directus-extension-blurhasher

Then restart Directus. The plugin will automatically perform a migration and be ready for use.

New Settings in Directus

After installing the plugin, two new settings appear in Directus:

1. Blurhasher Detail Level: Sets the level of detail (Low, Medium, High). Higher levels produce more accurate blur but require more processing time.
2. Blurhasher Regenerate on Restart: When enabled, instructs Directus to regenerate the Blurhash for all previously uploaded images on the next restart. Once the process is complete, this setting automatically turns off.

The Result

After installing the plugin, any file request (for example, GET https://localhost/files/{id}) returns a new blurhash field containing the generated Blurhash string. You can use this string in any frontend—Next.js, Flutter, or another framework—to display a blurred preview before the original image is fully loaded.

Below is an example API response showing the blurhash field:

{
  "data": {
    "id": "bca3eab2-12c3-49fc-9ae9-ce6c91b81166",
    "storage": "local",
    "filename_disk": "bca3eab2-12c3-49fc-9ae9-ce6c91b81166.jpg",
    "filename_download": "basta_1280х1280.jpg",
    "title": "Basta 1280х1280",
    "type": "image/jpeg",
    "folder": null,
    "uploaded_by": "3810105c-9a6c-41ec-bd43-867b9920bf77",
    "created_on": "2024-12-26T14:46:27.462Z",
    "modified_by": null,
    "modified_on": "2024-12-26T14:46:28.367Z",
    "charset": null,
    "filesize": "916978",
    "width": 1280,
    "height": 1280,
    "duration": null,
    "embed": null,
    "description": null,
    "location": null,
    "tags": null,
    "metadata": {},
    "focal_point_x": null,
    "focal_point_y": null,
    "tus_id": null,
    "tus_data": null,
    "uploaded_on": "2024-12-26T14:46:28.014Z",
    "blurhash": ":sIy@7}Q$fxHENf9n%R-=sX7Nxs.NHsms.R*aLR.Rkn$kBWVoJWXoMoeWBWCoeR+WCo1j?WXWDf6odfkWqoLxGWCWCj[WWj[ayj[s.WVWCoLa}j[jZjZsojtR+jss:a}WVa|"
  }
}

Now that you have the generated blurhash string, all that’s left is to display it on your frontend. There are plenty of libraries that can help you do just that—links and documentation can be found in the official BlurHash repository. Let’s keep pushing the boundaries of UX and make our interfaces as pleasant and responsive as possible!

Conclusion

Be sure to support the project on GitHub and share your integration experiences!