Qubo

Visual hash avatars with Bayer dithering and traditional Japanese colors from Nippon Colors.

Each avatar is deterministically generated from a string (username, email, ID) — the same input always produces the same avatar. Colors are selected from 250 traditional Japanese colors and rendered as OKLCH monotone gradients with an adjustable ordered dither pattern.

Features

• Deterministic — same input always generates the same avatar
• 250 traditional Japanese colors from nipponcolors.com
• OKLCH color space for perceptually uniform monotone gradients
• Bayer ordered dithering (4x4 or 8x8 matrix)
• Adjustable — control dither strength, pixel size, matrix type, and output size
• Zero dependencies — pure TypeScript, no external libraries
• Tiny bundle — ~8KB gzipped
• TypeScript types included

Install

pnpm add get-qubo

npm install get-qubo

yarn add get-qubo

Quick Start

import { qubo } from "get-qubo"

const { canvas, color } = qubo("Kairo")
document.body.appendChild(canvas)

console.log(color.name)  // e.g. "nakabeni"
console.log(color.cname) // e.g. "中紅"
console.log(color.color) // e.g. "#DB4D6D"

API

qubo(name, options?)

Generates an avatar and returns a canvas element plus the matched Japanese color.

const { canvas, color } = qubo("Sora", {
  size: 256,
  matrix: "bayer4x4",
  strength: 0.8,
  pixelSize: 3,
})

Returns: { canvas: HTMLCanvasElement, color: NipponColor }

quboDataURL(name, options?)

Generates an avatar and returns it as a base64 PNG data URL. Useful for <img> tags or storing in a database.

import { quboDataURL } from "get-qubo"

const src = quboDataURL("Hikari", { size: 128 })
document.querySelector("img").src = src

Returns: string (data URL)

quboBlob(name, options?)

Generates an avatar and returns it as a PNG Blob. Useful for file uploads or FormData.

import { quboBlob } from "get-qubo"

const blob = await quboBlob("Kumo", { size: 512 })
const formData = new FormData()
formData.append("avatar", blob, "avatar.png")

Returns: Promise<Blob>

quboRender(canvas, name, options?)

Renders an avatar into an existing canvas element. Useful for frameworks like React where you manage the canvas ref.

import { quboRender } from "get-qubo"

const canvas = document.getElementById("my-canvas")
const color = quboRender(canvas, "Ren", { size: 200 })

Returns: NipponColor

quboURL(baseURL, name, options?)

Builds an API URL for use in <img> tags. Point this at your deployed Qubo instance.

import { quboURL } from "get-qubo"

const url = quboURL("https://qubo.example.com", "Aoi", {
  size: 200,
  matrix: "bayer4x4",
})
// => "https://qubo.example.com/api/avatar?name=Aoi&matrix=bayer4x4&size=200"

Returns: string

Options

| Option | Type | Default | Description | | -------------- | -------------------------- | ------------ | --------------------------------------------------------------------------- | | size | number | 200 | Output size in pixels | | matrix | "bayer4x4" \| "bayer8x8" | "bayer4x4" | Dither matrix type | | strength | number (0–1) | 0.8 | Dither strength (0 = smooth, 1 = max) | | pixelSize | number (1–8) | 3 | Size of each dither "pixel" block | | borderRadius | number | size / 2 | Corner radius in pixels. 0 = square, size / 2 = fully round (default). |

Squared avatars

The default is a fully round avatar (borderRadius = size / 2). For a square or rounded-square shape, pass borderRadius explicitly:

// Fully square
quboDataURL("Kairo", { size: 256, borderRadius: 0 })

// Rounded square (e.g. 16px corners on a 256px avatar)
quboDataURL("Kairo", { size: 256, borderRadius: 16 })

Note: The shape is baked into the PNG itself — transparent pixels outside the rounded rectangle. You do not need to also apply border-radius in CSS.

Framework Examples

React

import { useRef, useEffect } from "react"
import { quboRender } from "get-qubo"

function Avatar({ name, size = 48 }: { name: string; size?: number }) {
  const ref = useRef<HTMLCanvasElement>(null)

  useEffect(() => {
    if (ref.current) {
      quboRender(ref.current, name, { size: size * 2 })
    }
  }, [name, size])

  return (
    <canvas
      ref={ref}
      style={{
        width: size,
        height: size,
        borderRadius: "50%",
        imageRendering: "pixelated",
      }}
    />
  )
}

Vue

<script setup lang="ts">
import { ref, onMounted, watch } from "vue"
import { quboRender } from "get-qubo"

const props = defineProps<{ name: string }>()
const canvas = ref<HTMLCanvasElement>()

function render() {
  if (canvas.value) quboRender(canvas.value, props.name, { size: 200 })
}

onMounted(render)
watch(() => props.name, render)
</script>

<template>
  <canvas ref="canvas" style="width:48px;height:48px;border-radius:50%;image-rendering:pixelated" />
</template>

Svelte

<script lang="ts">
  import { onMount } from "svelte"
  import { quboRender } from "get-qubo"

  export let name: string
  let canvas: HTMLCanvasElement

  onMount(() => quboRender(canvas, name, { size: 200 }))
  $: if (canvas) quboRender(canvas, name, { size: 200 })
</script>

<canvas bind:this={canvas} style="width:48px;height:48px;border-radius:50%;image-rendering:pixelated" />

Default Profile Image on Signup

import { quboDataURL } from "get-qubo"

async function createUser(name: string, email: string) {
  const avatar = quboDataURL(name, { size: 256 })

  await db.users.create({
    name,
    email,
    avatar, // base64 PNG — store directly or upload to S3/R2
  })
}

Advanced Exports

For lower-level use, the following are also exported:

import {
  // Color data
  NIPPON_COLORS,       // Full array of 250 Japanese colors
  type NipponColor,    // { id, name, cname, color }

  // Hashing
  hash,                // Deterministic hash function
  hashValues,          // Multiple hash-derived values from a string

  // Color conversion
  hexToOklch,          // Hex → OKLCH
  oklchToHex,          // OKLCH → Hex
  generateMonotoneGradient, // Generate gradient palette from a color

  // Dithering
  shouldDither,        // Per-pixel dither decision
  type DitherOptions,
  type DitherMatrix,

  // Core renderer
  renderAvatar,        // Full avatar renderer
  type AvatarConfig,
} from "get-qubo"

How It Works

1. Hash — The input string is hashed using a deterministic hash function (cyrb53) to produce stable numeric values
2. Color Selection — Hash values select a color from the 250 traditional Japanese colors
3. Gradient — An OKLCH monotone gradient is generated from the selected color, varying lightness while preserving hue
4. Dither — A Bayer ordered dithering matrix creates the pixel pattern, with the gradient direction determined by the hash
5. Render — The result is drawn pixel-by-pixel onto a canvas, masked to a circle

Development

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Build website + SDK
pnpm build

# Build SDK only
pnpm run build:lib

Tech Stack

• TypeScript — type-safe throughout
• Vite — dev server and build
• Tailwind CSS v4 — styling with shadcn/ui theme
• Canvas API — pixel-level rendering
• OKLCH — perceptually uniform color space

License

MIT