Halograph

Nuxt module that turns any image (including SVG) into a halftone: a grid of single-color dots with even spacing. Brightness is encoded by dot size, opacity, or both.

Minimal dependencies, maximum performance.

Features

• Halftone effects - scale (dot size), opacity, or both
• Flexible coloring - solid or gradient (2 or 3 colors); HEX, HSL, RGB(a), OKLCH
• Gradient control - direction in degrees, 2- or 3-color mode
• Dot shapes - circle, square, triangle
• Output - canvas or PNG image
• CORS - optional server proxy for external images
• Slots - #loading, #error
• Performance - maxWidth/maxHeight, Web Worker for large images (>512×512px), optional smoothing, trim, hideMinDots

Installation

npx nuxi module add halograph

Or manually:

npm install halograph

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['halograph'],
})

Usage

Component

<template>
  <HalographImage
    src="https://example.com/image.jpg"
    :options="halftoneOptions"
    output="canvas"
  />
</template>

<script setup lang="ts">
import type { HalftoneOptions } from 'halograph'

const halftoneOptions: HalftoneOptions = {
  dotType: 'circle',
  effectType: 'scale',
  color: '#1a1a1a',
  spacing: 8,
  maxWidth: 600,
}
</script>

Props

| Prop | Type | Default | Description | |-----------|------------------------|-----------|----------------| | src | string | - | Image URL | | options | HalftoneOptions | - | Effect options | | output | 'canvas' \| 'image' | 'canvas'| Output format |

Slots - #loading, #error (receives error).

Composable

<script setup lang="ts">
import { useHalograph } from 'halograph'

const src = '/image.jpg'
const options = {
  dotType: 'circle',
  effectType: 'scale',
  color: '#000000',
}

const { result, error, isLoading, toDataURL } = useHalograph(src, options)

const pngUrl = toDataURL('image/png')
</script>

Returns: result, error, isLoading, toDataURL(type?).

Options

| Option | Type | Default | Description | |-----------------|-------------------------|-----------|--------------------------------| | dotType | 'circle' \| 'square' \| 'triangle' | 'circle' | Dot shape | | effectType | 'scale' \| 'opacity' \| 'both' | 'scale' | Brightness encoding | | color | string | '#000000' | Dot color (HEX/RGB/HSL/OKLCH) | | colorMode | 'solid' \| 'gradient2' \| 'gradient3' | 'solid' | Coloring mode | | gradientColors| [string, string] or 3-tuple | - | Gradient stops | | gradientAngle | number | 90 | Gradient direction (degrees) | | spacing | number | auto | Distance between dots (px) | | maxWidth | number | - | Max width for performance | | maxHeight | number | - | Max height for performance | | smoothing | boolean | false | Supersampling for antialiasing | | trim | boolean | false | Crop canvas to content bounds (brightness > threshold) | | hideMinDots | boolean | false | Do not draw dots at minimum size/opacity (by effect type) |

Effect types

scale (default)

Dark areas = larger dots. Dot size reflects brightness.

{ effectType: 'scale', color: '#000' }

opacity

Dark areas = more transparent dots. Fixed size, opacity reflects brightness.

{ effectType: 'opacity', color: '#ff0000' }

both

Size and opacity both vary with brightness.

{ effectType: 'both', color: '#0000ff' }

Coloring

Solid

{ color: '#1a1a1a', colorMode: 'solid' }

Gradient (2 colors)

{
  colorMode: 'gradient2',
  gradientColors: ['#ff0000', '#0000ff'],
  gradientAngle: 45,
}

Gradient (3 colors)

{
  colorMode: 'gradient3',
  gradientColors: ['#ff0000', '#00ff00', '#0000ff'],
  gradientAngle: 90,
}

CORS and proxy

For images from other domains, enable the proxy:

// nuxt.config.ts
export default defineNuxtConfig({
  halograph: { useProxy: true },
})

The component will use /api/_halograph/proxy for external URLs.

Performance

Large images

const options: HalftoneOptions = {
  dotType: 'circle',
  effectType: 'scale',
  color: '#000',
  maxWidth: 800,
  maxHeight: 600,
  smoothing: false,
}

Smoothing (supersampling)

Improves quality at the cost of speed:

{ smoothing: true }

Trim

Crops canvas to the bounding box of cells with brightness above threshold:

{ trim: true }

Hide min dots

Skips drawing dots at minimum size (scale) or minimum opacity (opacity/both):

{ hideMinDots: true }

Exported types

import type {
  HalftoneOptions,
  HalftoneResult,
  DotType,
  EffectType,
  ColorMode,
} from 'halograph'

License

MIT © 2025