blur hash

This is the "blur-up" image loading technique, with the blur-hash algorithm, as a web component.

See a live demonstration

[!TIP] Throttle the internet speed with the dev tools.

• Install
• Modules
  • ESM
  • Common JS
• API
  • attributes
  • .reset
• CSS
  • Import CSS
  • variables
• use
  • Bundler
  • pre-built JS
• Create the string
  • JS API
  • CLI

Install

npm i -S @substrate-system/blur-hash

Modules

This exposes ESM and common JS via package.json exports field.

ESM

import { BlurHash } from '@substrate-system/blur-hash'

Common JS

require('@substrate-system/blur-hash')

API

attributes

Takes the following attributes

time

The time for css transitions and animation. This is set as a CSS variable.

placeholder

The string created by the blurhash algorithm. See node example.

width & height

The dimensions for the image

.reset

Change the image, and do the blur-up thing again.

Takes a new src string, new placeholder string, and all other attributes.

reset (attributes:{
  alt:string;
  width:string;
  height:string;
  placeholder:string;
  src:string;
  srcset?:string|null;
  sizes?:string|null;
  time?:number;
  contentVisibility?:'visible'|'auto'|'hidden'|null;
  decoding?:'sync'|'async'|'auto'|null;
  loading?:'lazy'|'eager'|'auto'|null;
}):void

.reset example

The reset method will be on the element once you call define.

import { BlurHash } from '@substrate-system/blur-hash'

BlurHash.define()

const el = document.querySelector('blur-hash')

el?.reset({
  src: 'llamas.jpg',
  alt: 'some llamas',
  placeholder: 'UgI}q#%O%eNa?^I?awaf?aIVs*WBxZxaRjR*'
})

CSS

Import CSS

import '@substrate-system/blur-hash/css'

Or minified:

import '@substrate-system/blur-hash/css/min'

variables

CSS variables

• --blur-hash-time -- the transition time for animating blurry -> sharp, default is 0.8s
• --blur-hash-opactiy -- the opacity to use for the placeholder image, default is 0.2

use

You will need to call the static method .define in JS to use the element.

Bundler

JS

import { BlurHash } from '@substrate-system/blur-hash'

BlurHash.define()

HTML

Use the tag in HTML.

<div>
    <blur-hash
        time="0.6s"
        placeholder="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
        src="..."
        width=100
        height=100
    >
    </blur-hash>
</div>

pre-built JS

This package exposes minified JS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.

copy

cp ./node_modules/@substrate-system/blur-hash/dist/blur-hash.min.js ./public

HTML

<script type="module" src="./blur-hash.min.js"></script>

Create the string

JS API

import { createString } from '@substrate-system/blur-hash/hash'

const hash = await createString('../example/100.jpg')
// => 'UHGIM_X900xC~XWFE0xt00o3%1oz-;t7i|IV'

CLI

This package includes a CLI tool to create the placeholder string. After installing this as a dependency,

npx blur ./my-file.jpg

Will print a string to stdout that can be used as a placeholder attribute.

Print to system clipboard

On mac os,

npx blur ./my-file.jpg | pbcopy