@jfcmontmorency/maze-widget

A lightweight, customizable maze generator with HTML5 Canvas rendering. Create beautiful, interactive mazes with configurable options and ES module support.

Features

• Customizable: Configure colors, dimensions, entry/exit points
• Deterministic: Use seeds for reproducible maze generation
• Responsive: Automatically adapts to container size
• Lightweight: Zero dependencies, pure JavaScript
• ES Modules: Modern JavaScript module support
• TypeScript Ready: Works seamlessly with TypeScript projects

Installation

npm install @jfcmontmorency/maze-widget

Quick Start

Basic Usage

import { createMazeWidget } from '@jfcmontmorency/maze-widget';

// Create a simple maze
const maze = createMazeWidget('#maze-container');

HTML Structure

<div id="maze-container" style="width: 400px; height: 400px;"></div>

API Reference

createMazeWidget(mount, options)

Creates a new maze widget instance.

Parameters

• mount {HTMLElement|string} - Container element or CSS selector
• options {Object} - Configuration options (optional)

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | cols | number | 5 | Number of columns in the maze | | rows | number | 5 | Number of rows in the maze | | wallColor | string | "#ffffff" | Color of the maze walls | | bgColor | string | "#000000" | Background color | | lineWidthRatio | number | 0.25 | Wall thickness as ratio of cell size | | seed | number | 983811 | Random seed for consistent maze generation | | entry | Object | {x: 0, y: 0, side: "top"} | Entry point configuration | | exit | Object | {x: null, y: null, side: "bottom"} | Exit point configuration | | squareBy | string | "width" | How to calculate dimensions ("width" or "min") | | padding | number | 0 | Internal padding in pixels |

Returns

An API object with the following methods:

• regenerate() - Generate a new maze with current options
• redraw() - Redraw the current maze
• setOptions(options) - Update options and redraw
• destroy() - Clean up and remove the widget
• getState() - Get current state (options, grid, canvas, mount)

Examples

Custom Styling

const maze = createMazeWidget('#container', {
  cols: 15,
  rows: 15,
  wallColor: '#ff6b6b',
  bgColor: '#4ecdc4',
  lineWidthRatio: 0.3,
  padding: 10
});

Using Seeds for Reproducible Mazes

// Generate the same maze every time
const maze = createMazeWidget('#container', {
  cols: 10,
  rows: 10,
  seed: 12345
});

// Generate a random maze
const randomMaze = createMazeWidget('#container', {
  seed: Math.floor(Math.random() * 1000000)
});

Dynamic Options

const maze = createMazeWidget('#container');

// Change maze size
maze.setOptions({ cols: 20, rows: 15 });

// Change colors
maze.setOptions({ 
  wallColor: '#2c3e50', 
  bgColor: '#ecf0f1' 
});

// Generate new maze with same settings
maze.regenerate();

Custom Entry and Exit Points

const maze = createMazeWidget('#container', {
  cols: 12,
  rows: 8,
  entry: { x: 0, y: 0, side: 'left' },
  exit: { x: 11, y: 7, side: 'right' }
});

Responsive Design

// The maze automatically adapts to container size
const maze = createMazeWidget('#responsive-container', {
  cols: 15,
  rows: 15,
  squareBy: 'min' // Use minimum of width/height for square cells
});

// Listen for container size changes
window.addEventListener('resize', () => {
  maze.redraw();
});

Advanced Usage

Getting Maze State

const maze = createMazeWidget('#container');
const state = maze.getState();

console.log(state.options);  // Current configuration
console.log(state.grid);     // Maze grid data
console.log(state.canvas);   // Canvas element
console.log(state.mount);    // Mount element

Cleanup

const maze = createMazeWidget('#container');

// Clean up when no longer needed
maze.destroy();

Browser Support

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+

Requires ES2020 support and Canvas API.

TypeScript

While this package is written in JavaScript, it works seamlessly with TypeScript projects:

import { createMazeWidget } from '@jfcmontmorency/maze-widget';

interface MazeOptions {
  cols?: number;
  rows?: number;
  wallColor?: string;
  bgColor?: string;
  // ... other options
}

const options: MazeOptions = {
  cols: 10,
  rows: 10,
  wallColor: '#333'
};

const maze = createMazeWidget('#container', options);

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © JF Cartier

Repository

https://github.com/jfcmontmorency/maze-widget