Word Search Puzzle Generator

A React component library for generating and playing interactive word search puzzles. Perfect for educational applications, games, and puzzle websites.

Used here: Word Search Games

Features

🎯 Complete Puzzle Generation

• Smart word placement algorithm
• Configurable grid sizes (5x5 to 25x25)
• Multiple direction support (horizontal, vertical, diagonal)
• Reverse word placement
• Random letter filling

🎮 Interactive Game Components

• Pre-built React components ready to use
• Mouse and touch support
• Visual feedback for selections and found words
• Customizable styling with CSS classes

⚙️ Highly Configurable

• Full TypeScript support
• Flexible API
• Custom styling options
• Zero dependencies (peer React only)

Screenshots

Interactive Game Grid

Play the word search by clicking and dragging to find words:

Installation

npm install word-search-puzzle-generator

Quick Start

import React, { useState } from 'react';
import { 
  PuzzleCreator, 
  WordSearchGrid, 
  generateGrid, 
  GridConfig, 
  PlacedWord 
} from 'word-search-puzzle-generator';

function App() {
  const [config, setConfig] = useState<GridConfig>({
    rows: 10,
    cols: 10,
    allowReverse: true,
    allowDiagonal: true,
    allowOverlap: false,
    fillBlanks: true
  });

  const [grid, setGrid] = useState<string[][]>([]);
  const [placedWords, setPlacedWords] = useState<PlacedWord[]>([]);

  const handleGenerate = (words: string[]) => {
    const result = generateGrid(words, config);
    setGrid(result.grid);
    setPlacedWords(result.placedWords);
  };

  const handleWordFound = (word: string) => {
    setPlacedWords(prev => 
      prev.map(pw => pw.word === word ? { ...pw, found: true } : pw)
    );
  };

  return (
    <div>
      <PuzzleCreator
        config={config}
        onConfigChange={setConfig}
        onGenerate={handleGenerate}
        initialWords={['REACT', 'TYPESCRIPT', 'PUZZLE']}
      />
      
      <WordSearchGrid
        grid={grid}
        placedWords={placedWords}
        onWordFound={handleWordFound}
      />
    </div>
  );
}

API Reference

generateGrid(words, config)

Generates a word search puzzle grid.

Parameters:

• words: string[] - Array of words to place in the grid
• config: GridConfig - Configuration options

Returns:

{
  grid: string[][];        // 2D array of letters
  placedWords: PlacedWord[] // Array of successfully placed words
}

Example:

const result = generateGrid(['HELLO', 'WORLD'], {
  rows: 10,
  cols: 10,
  allowReverse: true,
  allowDiagonal: true,
  allowOverlap: false,
  fillBlanks: true
});

<PuzzleCreator />

A form component for configuring and generating puzzles.

Props:

interface PuzzleCreatorProps {
  config: GridConfig;
  onConfigChange: (config: GridConfig) => void;
  onGenerate: (words: string[]) => void;
  initialWords?: string[];
  classNames?: {
    container?: string;
    section?: string;
    label?: string;
    input?: string;
    checkbox?: string;
    button?: string;
    error?: string;
  };
}

Example:

<PuzzleCreator
  config={config}
  onConfigChange={setConfig}
  onGenerate={handleGenerate}
  initialWords={['WORD', 'LIST']}
  classNames={{
    container: 'my-creator',
    button: 'my-button'
  }}
/>

<WordSearchGrid />

An interactive grid component for playing the word search game.

Props:

interface WordSearchGridProps {
  grid: string[][];
  placedWords: PlacedWord[];
  onWordFound: (word: string) => void;
  classNames?: {
    container?: string;
    grid?: string;
    row?: string;
    cell?: string;
    cellSelected?: string;
    cellFound?: string;
  };
}

Example:

<WordSearchGrid
  grid={grid}
  placedWords={placedWords}
  onWordFound={(word) => console.log(`Found: ${word}`)}
  classNames={{
    cell: 'my-cell',
    cellFound: 'my-cell-found'
  }}
/>

Type Definitions

GridConfig

interface GridConfig {
  rows: number;           // Number of rows (5-25)
  cols: number;           // Number of columns (5-25)
  allowReverse: boolean;  // Allow words to be placed backwards
  allowDiagonal: boolean; // Allow diagonal word placement
  allowOverlap: boolean;  // Allow words to share letters
  fillBlanks: boolean;    // Fill empty cells with random letters
}

PlacedWord

interface PlacedWord {
  word: string;           // The word that was placed
  path: Coordinate[];     // Array of grid coordinates
  found: boolean;         // Whether the word has been found
  color?: string;         // Optional color for the word
}

Coordinate

interface Coordinate {
  row: number;
  col: number;
}

Styling

The components use CSS classes that you can customize. Here's a basic example:

/* Grid cells */
.grid-cell {
  width: 40px;
  height: 40px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: bold;
  border: 1px solid #ddd;
  cursor: pointer;
}

/* Selected cells */
.grid-cell-selected {
  background-color: rgba(100, 108, 255, 0.5);
}

/* Found words */
.grid-cell-found {
  background-color: rgba(76, 175, 80, 0.5);
}

Example Application

Check out the /example directory for a complete working application with:

• Full game implementation
• Beautiful dark theme
• Mobile-friendly design
• Custom styling examples

To run the example:

cd example
npm install
npm run dev

Advanced Usage

Custom Word Validation

const handleWordFound = (word: string) => {
  // Custom logic before marking as found
  if (isValidWord(word)) {
    setPlacedWords(prev => 
      prev.map(pw => pw.word === word ? { ...pw, found: true } : pw)
    );
    
    // Award points, play sound, etc.
    awardPoints(word.length * 10);
  }
};

Generating Without UI

import { generateGrid } from 'word-search-puzzle-generator';

// Generate puzzle programmatically
const words = ['ALGORITHM', 'BINARY', 'CODE', 'DEBUG'];
const { grid, placedWords } = generateGrid(words, {
  rows: 15,
  cols: 15,
  allowReverse: true,
  allowDiagonal: true,
  allowOverlap: false,
  fillBlanks: true
});

// Use the grid however you need
console.log(grid);
console.log(placedWords);

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers with touch support

Contributing

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

License

MIT