@substrate-system/blur-hash NPM

blur hash

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

!TIP Throttle the internet speed with the dev tools.

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="..."
        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="..."
></blur-hash>

Server-side rendering

Following convention, this module exposes an html function at /ssr. It returns a plain string of appropriate markup in Node.

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

const htmlString = html({
    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.2

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'