Bulletproof browser-only utilities to convert profile pictures to WebP base64 text and render base64 back into images.
npm install avatar64File into WebP and return plain Base64 text
![]()
value
bash
npm install avatar64
`
`bash
yarn add avatar64
`
`bash
pnpm add avatar64
`
---
â ïļ Browser-only
This package uses Canvas API for image processing.
It must run in the browser.
> Importing or executing conversion functions on the server (Node.js / SSR) will throw an error with a clear message.
---
ð Quick Start
$3
`ts
import { fileToWebpBase64 } from "avatar64";
const input = document.querySelector("#file")!;
const output = document.querySelector("#out")!;
input.addEventListener("change", async () => {
const file = input.files?.[0];
if (!file) return;
try {
const { base64, width, height, decodedBytes } = await fileToWebpBase64(file, {
maxSize: 256,
quality: 0.8,
});
// Plain base64 text (NO data: prefix)
output.value = base64;
console.log( Converted to ${width}x${height}, ${decodedBytes} bytes);
} catch (error) {
console.error("Conversion failed:", error.message);
}
});
`
$3
`ts
type ConvertOptions = {
maxSize?: number; // default: 256px, set 0 to keep original size
quality?: number; // default: 0.8 (range: 0.1 to 1.0)
allowedMime?: string[]; // default: ["image/png", "image/jpeg", "image/webp", "image/gif"]
maxInputBytes?: number; // default: 6MB (6 1024 1024)
};
`
$3
`ts
type ConvertResult = {
base64: string; // Plain base64 text (NO data: prefix)
dataUrl: string; // Full data URL for immediate preview
width: number; // Output dimensions
height: number;
decodedBytes: number; // Exact size of WebP payload
};
`
---
ðžïļ Show: Base64 â Image
$3
`ts
import { base64ToImgSrc } from "avatar64";
try {
img.src = base64ToImgSrc(base64Text);
// â data:image/webp;base64,...
} catch (error) {
console.error("Invalid base64:", error.message);
}
`
$3
`ts
import { showBase64InImage } from "avatar64";
try {
showBase64InImage(img, base64Text);
} catch (error) {
console.error("Failed to display image:", error.message);
}
`
$3
`ts
type ShowOptions = {
mimeFallback?: string; // default: "image/webp"
stripWhitespace?: boolean; // default: true
maxBase64Chars?: number; // default: 3,000,000
maxDecodedBytes?: number; // default: 2MB (2 1024 1024)
};
`
---
ð Convert: Base64 â PNG File
$3
`ts
import { base64ToPngFile } from "avatar64";
try {
// Convert base64 back to a PNG File object
const pngFile = await base64ToPngFile(base64Text, "avatar.png");
// Now you can upload it to your server
const formData = new FormData();
formData.append("avatar", pngFile);
await fetch("/api/upload", {
method: "POST",
body: formData,
});
console.log(â Created PNG file: ${pngFile.name}, ${pngFile.size} bytes);
} catch (error) {
console.error("Conversion failed:", error.message);
}
`
$3
`ts
import { downloadBase64AsPng } from "avatar64";
try {
// Trigger immediate browser download
await downloadBase64AsPng(base64Text, "my-avatar.png");
console.log("â Download started");
} catch (error) {
console.error("Download failed:", error.message);
}
`
---
ð§ API Reference
$3
Converts an image File to WebP format and returns base64 text.
Parameters:
- file: File - Image file to convert
- options?: ConvertOptions - Optional conversion settings
Returns: Promise
Throws: Detailed error if file is invalid, too large, unsupported type, or conversion fails
---
$3
Converts base64 text or data URL to a safe value.
Parameters:
- base64OrDataUrl: string - Plain base64 or full data URL
- options?: ShowOptions - Optional display settings
Returns: string - Safe data URL for image src
Throws: Detailed error if input is invalid, corrupted, or exceeds safety limits
---
$3
Convenience function to directly set an image element's src.
Parameters:
- img: HTMLImageElement - Target image element
- base64OrDataUrl: string - Plain base64 or full data URL
- options?: ShowOptions - Optional display settings
Returns: void
Throws: Detailed error if element is invalid or base64 is corrupted
---
$3
Converts base64 text or data URL to a PNG File object.
Parameters:
- base64OrDataUrl: string - Plain base64 or full data URL
- filename?: string - Output filename (default: "image.png")
- options?: ShowOptions - Optional display settings
Returns: Promise - PNG File object ready for upload
Throws: Detailed error if input is invalid or conversion fails
Use cases:
- Upload base64 images to servers that require File objects
- Convert stored base64 back to files for FormData
- Programmatic file handling in web apps
---
$3
Converts base64 to PNG and triggers browser download.
Parameters:
- base64OrDataUrl: string - Plain base64 or full data URL
- filename?: string - Download filename (default: "image.png")
- options?: ShowOptions - Optional display settings
Returns: Promise
Throws: Detailed error if input is invalid or download fails
Use cases:
- "Save As" / "Download" buttons for profile pictures
- Export user-generated images
- Backup/download functionality
---
$3
Calculate the exact decoded byte size of a base64 string.
Parameters:
- base64: string - Base64 string to measure
Returns: number - Exact decoded bytes (0 if invalid)
---
ðĄïļ Safety Features
- â
Validates all inputs (File type, MIME, size, dimensions)
- â
Protects against corrupted or malicious files
- â
Prevents browser freezing with size limits
- â
Timeout protection for slow image loading
- â
Proper resource cleanup (blob URLs, canvas)
- â
Descriptive error messages for debugging
- â
Handles edge cases (empty files, invalid dimensions)
$3
| Limit | Default | Purpose |
|-------|---------|---------|
| maxInputBytes | 6 MB | Reject oversized input files |
| maxSize | 256px | Resize large images |
| maxBase64Chars | 3,000,000 | Prevent massive base64 strings |
| maxDecodedBytes | 2 MB | Limit decoded image size |
| Image dimensions | 16384Ã16384 | Prevent canvas errors |
| Load timeout | 30 seconds | Prevent hanging |
---
ð Notes & Limitations
- Base64 inflates size by ~33% compared to binary
- Output format for conversion is always WebP for optimal size/quality
- PNG conversion uses lossless encoding with full alpha channel support
- Browser support requires Canvas API (all modern browsers)
- Designed for avatars - profile pictures, not large photos
- No server-side support - browser environment required
- WebP encoding must be supported by browser (widely supported)
---
ðĄ Use Cases
- User profile picture uploads
- Avatar selection interfaces
- Image preview before upload
- Client-side image optimization
- Progressive web apps with offline image handling
- Chat applications with avatar display
- Account settings pages
- Download/export functionality for user images
- Converting stored base64 back to files for re-upload
---
ð Example: Complete Upload Flow
`ts
import { fileToWebpBase64, base64ToImgSrc } from "avatar64";
async function handleAvatarUpload(file: File) {
try {
// Convert to WebP base64
const result = await fileToWebpBase64(file, {
maxSize: 256,
quality: 0.85,
});
// Preview locally
const preview = document.querySelector("#preview")!;
preview.src = result.dataUrl;
// Send plain base64 to your API
await fetch("/api/profile/avatar", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ avatar: result.base64 }),
});
console.log( â Uploaded ${result.width}Ã${result.height} avatar);
} catch (error) {
console.error("Upload failed:", error.message);
alert(Failed to upload avatar: ${error.message});
}
}
// Later, display stored avatar
function displayAvatar(base64: string) {
const img = document.querySelector("#avatar")!;
try {
img.src = base64ToImgSrc(base64);
} catch (error) {
console.error("Failed to display avatar:", error.message);
img.src = "/default-avatar.png"; // fallback
}
}
`
---
ð Example: Base64 to PNG Conversion Flow
`ts
import { base64ToPngFile, downloadBase64AsPng } from "avatar64";
// Example 1: Upload stored base64 as a file
async function uploadStoredAvatar(base64: string) {
try {
// Convert base64 to PNG File
const pngFile = await base64ToPngFile(base64, "avatar.png");
// Upload using FormData
const formData = new FormData();
formData.append("avatar", pngFile);
await fetch("/api/upload", {
method: "POST",
body: formData,
});
console.log(â Uploaded ${pngFile.name});
} catch (error) {
console.error("Upload failed:", error.message);
}
}
// Example 2: Download button functionality
async function handleDownloadClick(base64: string) {
try {
await downloadBase64AsPng(base64, "my-profile-pic.png");
console.log("â Download started");
} catch (error) {
console.error("Download failed:", error.message);
alert(Failed to download: ${error.message});
}
}
// Example 3: Convert and get file for programmatic use
async function processAvatar(base64: string) {
try {
const pngFile = await base64ToPngFile(base64, "processed-avatar.png");
// Use the File object however you need
console.log(File created: ${pngFile.name});
console.log(Size: ${pngFile.size} bytes);
console.log(Type: ${pngFile.type});
// Can be used with any API that accepts File objects
return pngFile;
} catch (error) {
console.error("Processing failed:", error.message);
throw error;
}
}
``