Favium

Favium generates favicon assets from an HTMLCanvasElement in the browser and from image files in the terminal.

Features

• Generate multi-size ICO files from a canvas
• Generate PNG favicons at arbitrary sizes
• Produce a default favicon bundle or a custom size set
• Create text-based icons with configurable colors, corners, and pixel ratio
• Generate favicon files from local images or external image URLs through an interactive CLI

Installation

npm install favium

CLI

Favium ships with an interactive terminal workflow:

npx favium

The CLI can:

• scan the current directory for valid images
• accept a custom local file or directory path
• download and validate an external image URL
• generate default, web-app, apple-android, or fully custom icon sets
• choose output directory, base filename, fit mode, overwrite behavior, HTML snippet, and web manifest
• retry interactive prompts when an entered path, URL, or size list is invalid

By default, Favium writes generated assets into a same-name directory beside the source image.

Example:

source: ./logo.png
output: ./logo/

If the source is ./logo.png and the base name stays logo, generated files typically include:

• logo.ico
• favicon-16x16.png
• favicon-32x32.png
• apple-touch-icon.png
• android-chrome-192x192.png
• android-chrome-512x512.png
• logo.html
• manifest.webmanifest

Non-interactive example:

favium --source ./logo.png --preset web-app --yes

CLI options:

-h, --help       Show this help message
-v, --version    Show the current version
--source         Local file, local directory, or external image URL
--output         Output directory
--preset         default | web-app | apple-android | custom
--recursive      Recursively scan directories for valid images
-y, --yes        Accept defaults for optional prompts

Preset summary:

• default: classic favicon output including favicon-16x16.png, favicon-32x32.png, apple-touch-icon.png, android-chrome-192x192.png, android-chrome-512x512.png, mstile-150x150.png, HTML, and manifest.webmanifest
• web-app: broader modern set including extra 64, 128, and 256 PNG outputs plus favicon.ico
• apple-android: focused mobile-oriented set with Apple touch icon, Android icons, and a smaller ICO
• custom: custom PNG sizes and ICO sizes, with filenames generated from the chosen base name

Requirements

• Browser or browser-like runtime with document, HTMLCanvasElement, and CanvasRenderingContext2D
• Canvas content must be origin-clean if you want getImageData() and toDataURL() to succeed

Quick Start

import { FaviconComposer } from "favium";

const canvas = document.createElement("canvas");
canvas.width = 512;
canvas.height = 512;

const ctx = canvas.getContext("2d");
if (!ctx) throw new Error("2D context unavailable");

ctx.fillStyle = "#2563eb";
ctx.fillRect(0, 0, 512, 512);

const favicon = new FaviconComposer(canvas);
const bundle = favicon.bundle();

console.log(bundle.ico);
console.log(bundle.png32);
console.log(bundle.png512);
console.log(bundle.pngs[180]);

API

Top-level exports:

import {
  CanvasResize,
  FaviconComposer,
  IcoGenerator,
  ImageBundleGenerator,
  PngGenerator,
  TextIconGenerator,
} from "favium";

FaviconComposer

import { FaviconComposer } from "favium";

const favicon = new FaviconComposer(canvas);

const ico = favicon.ico([16, 32, 64, 256]);
const png = favicon.png(180);
const resized = favicon.resize(128);
const bundle = favicon.bundle();
const customBundle = favicon.bundle({
  icoSizes: [32, 64, 256],
  pngSizes: [64, 128, 256, 512],
});

bundle() returns the legacy named PNG fields plus a pngs size map:

{
  ico: string,
  pngs: Record<number, string>,
  png16: string,
  png32: string,
  png150: string,
  png180: string,
  png192: string,
  png512: string
}

When you pass custom bundle options, the result always includes:

{
  ico: string,
  pngs: Record<number, string>
}

Named fields such as png32 or png512 are also included when those standard sizes are part of pngSizes.

TextIconGenerator

import { TextIconGenerator } from "favium";

const canvas = document.createElement("canvas");

new TextIconGenerator(canvas).generate({
  text: "F",
  width: 128,
  height: 128,
  backgroundColor: "#111827",
  fontColor: "#ffffff",
  cornerRadius: 24,
  pixelRatio: window.devicePixelRatio,
});

You can also create a new canvas directly:

const iconCanvas = TextIconGenerator.generate({
  text: "A",
  backgroundColor: "#dc2626",
});

If pixelRatio is omitted, Favium uses window.devicePixelRatio when available and falls back to 1.

Notes

• ICO generation uses PNG-compressed payloads for 256x256 entries to improve compatibility with common icon readers.
• IcoGenerator.generate() requires at least one size.
• Resize progressively downsamples large canvases before the final draw for better output quality.
• The CLI uses Sharp and png-to-ico to generate real favicon files in Node.js.
• CLI manifest output is written as manifest.webmanifest.

License

MIT © Toufiq Hasan Kiron

"From canvas to favicon, your icon journey starts here." - Favium Motto