VueCraft NPM

Placeholder State ​

usePlaceholder() (hazehash-vue) — the reactive state behind <PlaceholderImage> for a hash: the canvas ref to draw into, the average colour, the aspect ratio and a flag that tells when the page is on the client. Use it to build your own markup around a placeholder.

ts
function usePlaceholder(
  hash: MaybeRefOrGetter<string | Uint8Array | undefined | null>,
  options?: UsePlaceholderOptions,
): UsePlaceholderReturn
vue
<script setup lang="ts">
import { usePlaceholder } from 'hazehash-vue'

const props = defineProps<{ hash: string }>()
const { canvas, backgroundColor, aspectRatio } = usePlaceholder(() => props.hash)
</script>

<template>
  <div class="card" :style="{ backgroundColor, aspectRatio }">
    <canvas ref="canvas" aria-hidden="true" />
  </div>
</template>

On the server only backgroundColor and aspectRatio have values. The canvas is drawn after the component is mounted, so the server markup and the first client render never differ. The hash can be a plain value, a ref or a getter, and the canvas is redrawn when it changes. In Nuxt the composable is auto-imported.

Parameters ​

hash ​

MaybeRefOrGetter<string | Uint8Array | undefined | null>

The hash to show. undefined, null and an empty string mean "no placeholder yet": every value stays empty. An invalid hash does not throw; the values stay empty and the console gets a single [hazehash-vue] invalid placeholder hash: warning for the whole page.

options ​

UsePlaceholderOptions · optional

An object with one field:

  • size — MaybeRefOrGetter<number | undefined> · default: 32. The long side of the decoded preview, limited to 4–128 like the size option of decode(). It can be reactive, and a change redraws the canvas.

Return value ​

canvas ​

Ref<HTMLCanvasElement | null>

A template ref. Put ref="canvas" on a <canvas> and the composable draws the preview into it after mount and whenever the hash or size changes. The canvas takes the pixel size of the preview, so give it a CSS size that fills your box.

mounted ​

Ref<boolean>

false on the server and during the first client render, true after the component is mounted. Use it to render the <canvas> only on the client, as the component does.

average ​

ComputedRef<{ r: number; g: number; b: number; a: number } | undefined>

The average colour of the hash, as returned by getAverageColor(), or undefined when there is no valid hash. It is available on the server too.

backgroundColor ​

ComputedRef<string | undefined>

The average colour as a CSS rgba(r, g, b, a) string, ready for background-color, or undefined.

aspectRatio ​

ComputedRef<number | undefined>

The aspect ratio of the hash as a number, as returned by getAspectRatio(), or undefined. Pass it to the CSS aspect-ratio property.

Example — the placeholder shown only on the client, with a larger preview:

vue
<script setup lang="ts">
import { usePlaceholder } from 'hazehash-vue'

const props = defineProps<{ hash: string; src: string }>()
const { canvas, mounted, backgroundColor, aspectRatio } = usePlaceholder(() => props.hash, {
  size: 64,
})
</script>

<template>
  <div class="frame" :style="{ backgroundColor, aspectRatio }">
    <canvas v-if="mounted" ref="canvas" aria-hidden="true" />
    <img :src="src" alt="" />
  </div>
</template>