Skip to content

Commit 97dd4d1

Browse files
johannschopplichjohannschopplich
committed
docs: emphasize performance consideraions with BlurHash (related to #67)
1 parent 4ec7ae9 commit 97dd4d1

File tree

7 files changed

+84
-2
lines changed

7 files changed

+84
-2
lines changed

‎docs/api/create-placeholder-from-hash.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ The function accepts an options object with the following properties:
1414
- `hash`: The hash string to decode. If both `image` and `hash` are provided, `hash` takes precedence
1515
- `hashType`: Specifies whether the hash is a `blurhash` or `thumbhash`. Default is `blurhash`. If `image` is provided, the type is determined from the presence of `data-blurhash` or `data-thumbhash` attributes
1616
- `size`: The size of the longer edge for BlurHash decoding. Default is `32`. This parameter is ignored for ThumbHash
17-
- `ratio`: The aspect ratio (width divided by height) for BlurHash. If `image` is provided, this is calculated automatically from the element's dimensions
17+
- `ratio`: The aspect ratio (width divided by height) for BlurHash. If `image` is provided, this is calculated automatically using: `(width || offsetWidth || size) / (height || offsetHeight || size)`. For optimal performance, set explicit `width` and `height` HTML attributes to avoid falling back to rendered dimensions
1818

1919
## Return Value
2020

@@ -53,6 +53,15 @@ if (placeholder) {
5353
}
5454
```
5555

56+
```html
57+
<!-- Ensure the image has width and height attributes for optimal performance -->
58+
<img
59+
width="800"
60+
height="600"
61+
data-blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
62+
>
63+
```
64+
5665
::: tip
5766
For server-side rendering, use the specialized functions instead:
5867
- [`createPngDataUri`](/api/blurhash-create-png-data-uri) from `unlazy/blurhash`

‎docs/integrations/nuxt.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,8 @@ const exampleSources = [
174174
175175
<template>
176176
<UnLazyImage
177+
width="800"
178+
height="600"
177179
:src="exampleImgSrc"
178180
:sources="exampleSources"
179181
blurhash="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
@@ -189,9 +191,16 @@ Useful if the `UnLazyImage` is part of e.g. a slider, and you want to preload th
189191
```vue
190192
<template>
191193
<UnLazyImage
194+
width="640"
195+
height="320"
192196
:blurhash="blurhash"
193197
src-set="image-320w.jpg 320w, image-640w.jpg 640w"
194198
auto-sizes
195199
preload
196200
/>
197201
</template>
202+
```
203+
204+
::: info
205+
When using client-side BlurHash decoding (`:ssr="false"`), set explicit `width` and `height` attributes for optimal performance. Server-side rendering (enabled by default) is less affected by this, but including these attributes is still recommended as a best practice.
206+
:::

‎docs/integrations/react.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@ The component uses React's `useEffect` hook to initialize lazy loading when moun
7373
```tsx [BlurHash]
7474
return (
7575
<UnLazyImage
76+
width={800}
77+
height={600}
7678
blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
7779
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
7880
autoSizes
@@ -82,6 +84,8 @@ The component uses React's `useEffect` hook to initialize lazy loading when moun
8284
```tsx [ThumbHash]
8385
return (
8486
<UnLazyImage
87+
width={800}
88+
height={600}
8589
thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
8690
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
8791
autoSizes
@@ -91,6 +95,8 @@ The component uses React's `useEffect` hook to initialize lazy loading when moun
9195
```tsx [Inlined placeholder image]
9296
return (
9397
<UnLazyImage
98+
width={800}
99+
height={600}
94100
placeholderSrc="data:image/svg+xml, ..."
95101
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
96102
autoSizes
@@ -102,3 +108,7 @@ The component uses React's `useEffect` hook to initialize lazy loading when moun
102108
::: tip
103109
In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
104110
:::
111+
112+
::: info
113+
When using BlurHash, set explicit `width` and `height` props for optimal performance. Without these, BlurHash decoding falls back to rendered dimensions, which may cause performance delays on large images.
114+
:::

‎docs/integrations/solid.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ This component uses Solid.js's fine-grained reactivity primitives:
7272
```tsx [BlurHash]
7373
return (
7474
<UnLazyImage
75+
width={800}
76+
height={600}
7577
blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
7678
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
7779
autoSizes
@@ -81,6 +83,8 @@ This component uses Solid.js's fine-grained reactivity primitives:
8183
```tsx [ThumbHash]
8284
return (
8385
<UnLazyImage
86+
width={800}
87+
height={600}
8488
thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
8589
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
8690
autoSizes
@@ -90,6 +94,8 @@ This component uses Solid.js's fine-grained reactivity primitives:
9094
```tsx [Inlined placeholder image]
9195
return (
9296
<UnLazyImage
97+
width={800}
98+
height={600}
9399
placeholderSrc="data:image/svg+xml, ..."
94100
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
95101
autoSizes
@@ -98,6 +104,10 @@ This component uses Solid.js's fine-grained reactivity primitives:
98104
```
99105
:::
100106

107+
::: info
108+
When using BlurHash, set explicit `width` and `height` props for optimal performance. Without these, BlurHash decoding falls back to rendered dimensions, which may cause performance delays on large images.
109+
:::
110+
101111
::: tip
102112
In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
103113
:::

‎docs/integrations/svelte.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,27 +68,37 @@ This component is built using Svelte 5's modern runes syntax:
6868
::: code-group
6969
```svelte [BlurHash]
7070
<UnLazyImage
71+
width={800}
72+
height={600}
7173
blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
7274
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
7375
autoSizes
7476
/>
7577
```
7678
```svelte [ThumbHash]
7779
<UnLazyImage
80+
width={800}
81+
height={600}
7882
thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
7983
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
8084
autoSizes
8185
/>
8286
```
8387
```svelte [Inlined placeholder image]
8488
<UnLazyImage
89+
width={800}
90+
height={600}
8591
placeholderSrc="data:image/svg+xml, ..."
8692
srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
8793
autoSizes
8894
/>
8995
```
9096
:::
9197

98+
::: info
99+
When using BlurHash, set explicit `width` and `height` props for optimal performance. Without these, BlurHash decoding falls back to rendered dimensions, which may cause performance delays on large images.
100+
:::
101+
92102
::: tip
93103
In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
94104
:::

‎docs/integrations/vue.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,20 +94,26 @@ The component uses Vue's `watchEffect` to handle reactive updates:
9494
::: code-group
9595
```html [BlurHash]
9696
<UnLazyImage
97+
width="800"
98+
height="600"
9799
blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
98100
src-set="image-320w.jpg 320w, image-640w.jpg 640w"
99101
auto-sizes
100102
/>
101103
```
102104
```html [ThumbHash]
103105
<UnLazyImage
106+
width="800"
107+
height="600"
104108
thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
105109
src-set="image-320w.jpg 320w, image-640w.jpg 640w"
106110
auto-sizes
107111
/>
108112
```
109113
```html [Inlined placeholder image]
110114
<UnLazyImage
115+
width="800"
116+
height="600"
111117
placeholder-src="data:image/svg+xml, ..."
112118
src-set="image-320w.jpg 320w, image-640w.jpg 640w"
113119
auto-sizes
@@ -119,6 +125,10 @@ The component uses Vue's `watchEffect` to handle reactive updates:
119125
In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
120126
:::
121127

128+
::: info
129+
When using BlurHash, set explicit `width` and `height` attributes for optimal performance. Without these, BlurHash decoding falls back to rendered dimensions, which may cause performance delays on large images.
130+
:::
131+
122132
### Preload Image
123133

124134
Useful if the `UnLazyImage` is part of e.g. a slider, and you want to preload the next image.

‎docs/placeholders/hash-based.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,23 @@ ThumbHash strings are typically shorter and produce higher quality placeholders,
2525

2626
By default, unlazy automatically decodes hash strings when a `data-blurhash` or `data-thumbhash` attribute is present on an `<img>` tag.
2727

28+
::: warning
29+
For optimal performance when using BlurHash, always set explicit `width` and `height` attributes on your images. Without these attributes, the library falls back to the rendered dimensions (`offsetWidth`/`offsetHeight`), which can cause BlurHash to decode at full image size instead of the default 32px. This may result in significant performance delays on large images.
30+
:::
31+
2832
::: code-group
2933
```html [BlurHash]
3034
<img
35+
width="800"
36+
height="600"
3137
data-src="image.jpg"
3238
data-blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
3339
>
3440
```
3541
```html [ThumbHash]
3642
<img
43+
width="800"
44+
height="600"
3745
data-src="image.jpg"
3846
data-thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
3947
>
@@ -68,7 +76,7 @@ When initializing unlazy for single images (e.g., in a framework component), you
6876
:::
6977

7078
::: info
71-
The `hashType` defaults to `blurhash` if not specified.
79+
The `hashType` defaults to `blurhash` if not specified. For BlurHash, ensure the image element has `width` and `height` attributes set for optimal performance.
7280
:::
7381

7482
### Disabling Hash Decoding
@@ -106,3 +114,19 @@ For a complete list of options, see the API documentation:
106114

107115
- BlurHash [`createPngDataUri`](/api/blurhash-create-png-data-uri)
108116
- ThumbHash [`createPngDataUri`](/api/thumbhash-create-png-data-uri)
117+
118+
## Hash Decoding Strategies
119+
120+
Both approaches have distinct characteristics that affect bundle size and user experience:
121+
122+
### Client-Side Decoding
123+
124+
Requires including the hash decoding library in your JavaScript bundle, which increases bundle size. However, placeholders are visible immediately on page load, providing instant visual feedback to users.
125+
126+
### Server-Side Decoding
127+
128+
Generates PNG data URIs on the server, keeping your client bundle smaller. The placeholder image is embedded directly in the HTML as a data URI. This approach is ideal when minimizing client-side JavaScript is a priority.
129+
130+
::: tip
131+
ThumbHash is more efficient for both approaches due to its smaller hash size and faster decoding performance compared to BlurHash.
132+
:::

0 commit comments

Comments
 (0)