monoink

1.0.1 • Public • Published

MonoInk.js

A lightweight JavaScript library that applies authentic retro computer display effects to web content. Render any webpage with a retro screen effect using pixelation, dithering, high contrast, and backlight effects reminiscent of classic CRT monitors and early computer displays.

Features

  • Pixelation: Create chunky, low-resolution blocks (1-100 density levels)
  • Dithering: Floyd-Steinberg algorithm for authentic black/white dot patterns
  • High Contrast: Force colors to pure black or white
  • Backlight: Colored lighting effects like vintage CRT monitors
  • Performance Optimized: Canvas reuse, 60fps throttling, memory leak prevention
  • Cross-Origin Safe: Graceful handling of CORS-restricted content
  • Real-time Updates: Dynamic settings changes without reinitialization

Installation

NPM

npm install monoink

Direct Download

<script src="monoink.js"></script>

CDN

<!-- Latest version -->
<script src="https://unpkg.com/monoink@latest/monoink.js"></script>

<!-- Specific version -->
<script src="https://unpkg.com/monoink@1.0.0/monoink.js"></script>

ES Modules

import MonoInk from 'monoink';

Install from GitHub

# Install latest release
npm install git+https://github.com/olgv/tool-monoink.git

# Install specific version
npm install git+https://github.com/olgv/tool-monoink.git#v1.0.0

# Install from develop branch
npm install git+https://github.com/olgv/tool-monoink.git#develop

Quick Start

Render Entire Page

// Apply effects to the entire webpage
const monoInk = new MonoInk({
    pixelation: true,
    pixelDensity: 4,
    dithering: true,
    ditherDensity: 2
});

monoInk.render();

Render Specific Element

// Apply effects to a specific div or element
const targetDiv = document.getElementById('my-content');
const monoInk = new MonoInk({
    targetElement: targetDiv,
    pixelation: true,
    pixelDensity: 6,
    dithering: true
});

monoInk.render();

API Reference

Constructor

new MonoInk(options)

Options

Parameter Type Default Range Description
pixelDensity number 4 1-100 Size of pixelated blocks. Higher = chunkier pixels
ditherDensity number 2 1-10 Fineness of dithering dots. Lower = finer dots
pixelation boolean false - Enable/disable pixelation effect
dithering boolean false - Enable/disable dithering effect
highContrast boolean true - Force similar colors to pure black/white
backlight boolean false - Enable colored backlight effect
backlightColor object {r:255,g:165,b:0} RGB 0-255 Backlight color
targetElement Element document.body - DOM element to apply effects to
toggleButtonSelector string "#toggle-backlight" - CSS selector for toggle button

Methods

render()

Applies the current effects to the target element.

monoInk.render();

updateSettings(newSettings)

Dynamically update effect parameters without recreating the instance.

monoInk.updateSettings({
    pixelDensity: 8,
    dithering: true,
    backlightColor: { r: 0, g: 255, b: 0 }
});

toggleBacklight()

Toggle the backlight effect on/off.

await monoInk.toggleBacklight();

destroy()

Clean up resources and remove effects.

monoInk.destroy();

Usage Examples

Basic Retro Effect

const monoInk = new MonoInk({
    pixelation: true,
    pixelDensity: 6,
    dithering: true,
    ditherDensity: 1,
    highContrast: true
});

monoInk.render();

Vintage Terminal Look

const monoInk = new MonoInk({
    pixelation: false,
    dithering: true,
    ditherDensity: 3,
    backlight: true,
    backlightColor: { r: 0, g: 255, b: 0 }, // Green CRT
    highContrast: true
});

monoInk.render();

Multiple Elements with Different Effects

// Apply different effects to different sections
const header = document.getElementById('header');
const content = document.getElementById('main-content');

// Subtle effect for header
const headerEffects = new MonoInk({
    targetElement: header,
    pixelation: true,
    pixelDensity: 2,
    highContrast: false
});

// Stronger effect for main content
const contentEffects = new MonoInk({
    targetElement: content,
    pixelation: true,
    pixelDensity: 8,
    dithering: true,
    backlight: true,
    backlightColor: { r: 0, g: 255, b: 0 }
});

headerEffects.render();
contentEffects.render();

Dynamic Controls

const monoInk = new MonoInk();

// Create control interface
document.getElementById('pixel-slider').addEventListener('input', (e) => {
    monoInk.updateSettings({ 
        pixelation: true,
        pixelDensity: parseInt(e.target.value) 
    });
});

document.getElementById('dither-slider').addEventListener('input', (e) => {
    monoInk.updateSettings({ 
        dithering: true,
        ditherDensity: parseInt(e.target.value) 
    });
});

Color Picker Integration

document.getElementById('color-picker').addEventListener('change', (e) => {
    const hex = e.target.value;
    const r = parseInt(hex.slice(1, 3), 16);
    const g = parseInt(hex.slice(3, 5), 16);
    const b = parseInt(hex.slice(5, 7), 16);
    
    monoInk.updateSettings({
        backlight: true,
        backlightColor: { r, g, b }
    });
});

Effect Combinations

Pixelated Dithering

When both pixelation and dithering are enabled, MonoInk creates large pixelated blocks with fine dithering patterns within each block:

// Large blocks with fine internal dithering
const monoInk = new MonoInk({
    pixelation: true,
    pixelDensity: 20,    // Very chunky blocks
    dithering: true,
    ditherDensity: 1     // Very fine dots within blocks
});

Independent Effects

Effects can be combined or used separately:

  • Pixelation only: Chunky, blocky appearance
  • Dithering only: Fine black/white dot patterns
  • High Contrast only: Pure black/white conversion
  • Backlight only: Colored overlay effect

Performance Notes

  • Canvas Reuse: Canvases are reused to minimize memory allocation
  • Frame Rate Limiting: Automatic 60fps throttling prevents excessive rendering
  • Lazy Rendering: Effects only apply when enabled
  • Memory Management: Proper cleanup prevents memory leaks
  • CORS Handling: Graceful degradation for cross-origin images

Browser Support

  • Modern browsers with Canvas 2D support
  • Chrome 60+, Firefox 55+, Safari 11+, Edge 79+
  • Mobile browsers supported

Error Handling

MonoInk includes robust error handling:

try {
    const monoInk = new MonoInk({
        pixelDensity: -5  // Invalid value
    });
} catch (error) {
    console.error('MonoInk initialization failed:', error.message);
}

Common errors:

  • Invalid parameter types or ranges
  • Missing target elements
  • Canvas creation failures
  • CORS-restricted content (handled gracefully)

CSS Integration

The effect canvas is automatically styled and positioned:

/* MonoInk canvas styling (automatic) */
canvas {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    pointer-events: none;
    z-index: 9998;
}

To customize or hide specific elements from effects:

.no-monoink {
    /* Elements with this class will be skipped */
}

Advanced Usage

Multiple Instances

// Different effects for different areas
const headerEffects = new MonoInk({
    targetElement: document.header,
    pixelation: true,
    pixelDensity: 3
});

const contentEffects = new MonoInk({
    targetElement: document.main,
    dithering: true,
    ditherDensity: 2
});

Animation Integration

// Animate pixel density over time
let density = 1;
setInterval(() => {
    density = (density % 10) + 1;
    monoInk.updateSettings({ pixelDensity: density });
}, 200);

Responsive Design

// Adjust effects based on screen size
function updateForScreenSize() {
    const isMobile = window.innerWidth < 768;
    monoInk.updateSettings({
        pixelDensity: isMobile ? 2 : 4,
        ditherDensity: isMobile ? 4 : 2
    });
}

window.addEventListener('resize', updateForScreenSize);

Cleanup

Always clean up when done:

// Before page unload
window.addEventListener('beforeunload', () => {
    monoInk.destroy();
});

// Or when switching views
function cleanup() {
    monoInk.destroy();
}

Demo

You can see MonoInk.js in action by opening the included index.html file in your browser, or visit the online demo at: GitHub Pages Demo

License

MIT License - Feel free to use in personal and commercial projects.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone the repository
git clone https://github.com/olgv/tool-monoink.git
cd tool-monoink

# No dependencies to install - pure vanilla JS!
# Open index.html in your browser to test changes

Guidelines

  • Code follows existing style
  • Performance optimizations are maintained
  • Cross-browser compatibility is preserved
  • Test thoroughly before submitting

Package Sidebar

Install

npm i monoink

Weekly Downloads

4

Version

1.0.1

License

MIT

Unpacked Size

27.1 kB

Total Files

4

Last publish

Collaborators

  • olgv