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.

Contents

• Install
• Modules
  • ESM
  • CJS
  • Bundler
  • pre-built JS
• Use
  • Server-side rendering
• API
  • Attributes
  • .reset
• CSS
  • Import CSS
  • variables
• Create the blur-hash 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'

CJS

const blurHash = require('@substrate-system/blur-hash')

Bundler

Just import like normal.

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/index.min.js ./public/blur-hash.min.js

HTML

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

Use the tag in HTML.

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

Use

Call the static method .define in JS, then use the tag in HTML.

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

BlurHash.define()

<blur-hash
  alt="cool cat"
  placeholder="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
  width=100
  height=100
  src="/example/cat.png"
></blur-hash>

Server-side rendering

Following convention, this module exposes render function at /html. It returns a plain string of markup.

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

const htmlString = render({
    alt: 'hello',
    width: 30,
    height: 30,
    placeholder: 'UHGIM_X900xC~XWFE0xt00o3%1oz-;t7i|IV',
    src: 'abc.jpg'
})

API

Attributes

The required attributes are alt, src, placeholder, width, and height.

type Attrs = {
  alt:string;
  width:string|number;
  height:string|number;
  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;
}

---

other attributes

time

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

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.

If width and height are not passed in, it will keep the existing width and height.

reset (attributes:{
  src:string;
  alt:string;
  placeholder:string;
  width?:string;
  height?: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.4

Create the blur-hash string

Use Node to create the placeholder attribute, the string consumed by blur-hash.

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