Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jaredreisinger/react-crossword
A flexible, responsive, and easy-to-use crossword component for React apps.
https://github.com/jaredreisinger/react-crossword
crossword library puzzle react react-component
Last synced: 7 days ago
JSON representation
A flexible, responsive, and easy-to-use crossword component for React apps.
- Host: GitHub
- URL: https://github.com/jaredreisinger/react-crossword
- Owner: JaredReisinger
- License: mit
- Created: 2019-12-27T01:55:29.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-10-15T05:36:49.000Z (23 days ago)
- Last Synced: 2024-10-30T17:04:38.090Z (7 days ago)
- Topics: crossword, library, puzzle, react, react-component
- Language: TypeScript
- Homepage: https://react-crossword.jaredreisinger.com
- Size: 27.2 MB
- Stars: 182
- Watchers: 4
- Forks: 84
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 
[](https://www.npmjs.com/package/@jaredreisinger/react-crossword)
[](https://github.com/JaredReisinger/react-crossword/actions/workflows/build.yml)
[](https://codecov.io/gh/JaredReisinger/react-crossword)
[](https://snyk.io/test/github/JaredReisinger/react-crossword?targetFile=package.json)
[](https://libraries.io/npm/@jaredreisinger%2Freact-crossword)
[](./LICENSE)
[](http://commitizen.github.io/cz-cli/)
[](https://github.com/semantic-release/semantic-release)
[](#contributors-)
Please see the [complete docs](https://react-crossword.jaredreisinger.com) for in-depth details.
- [Install](#install)
- [Usage](#usage)
- [Clue/data format](#cluedata-format)
- [Styling](#styling)
- [Player progress events](#player-progress-events)
- [Imperative methods](#imperative-methods)
- [Background](#background)
- [Contributors ✨](#contributors-)
---
## Install
```sh
npm install --save @jaredreisinger/react-crossword
# or #
yarn add @jaredreisinger/react-crossword
```
## Usage
```javascript
import React from 'react';
import Crossword from '@jaredreisinger/react-crossword';
const data = {
/* ... puzzle data (see below) ... */
};
export default function MyPage() {
return ;
}
```
### Clue/data format
To make crosswords as easy to create as possible, with the least amount of extraneous and boilerplate typing, the clue/answer format is structured as a set of nested objects:
```javascript
{
across: {
1: {
clue: 'one plus one',
answer: 'TWO',
row: 0,
col: 0,
},
},
down: {
2: {
clue: 'three minus two',
answer: 'ONE',
row: 0,
col: 2,
},
},
}
```
At the top level, the `across` and `down` properties group together the clues/answers for their respective directions. Each of those objects is a map, keyed by the answer number rather than an array. (This is done so that the creator has control over the numbering/labelling of the clues/answers.) Each item contains a `clue` and `answer` property, as well as `row` and `col` for the starting position.
The `Crossword` component calculates the needed grid size from the data itself, so you don't need to pass an overall size to the component.
## Styling
One other major difference (and advantage) to this crossword component is that it is very "stylable"... as many of the styling properties as possible are exposed so that you can create any look you want for the crossword. The `Crossword` component makes use of [styled-components' `ThemeProvider`](https://styled-components.com/docs/advanced#theming) and offers the following properties to control colors and layout:
| theme property | default | description |
| --------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columnBreakpoint` | `'768px'` | browser-width at which the clues go from showing beneath the grid to showing beside the grid. |
| `gridBackground` | `'rgb(0,0,0)'` | overall background color (fill) for the crossword grid. Can be `'transparent'` to show through a page background image. |
| `cellBackground` | `'rgb(255,255,255)'` | background for an answer cell |
| `cellBorder` | `'rgb(0,0,0)'` | border for an answer cell |
| `textColor` | `'rgb(0,0,0)'` | color for answer text (entered by the player) |
| `numberColor` | `'rgba(0,0,0, 0.25)'` | color for the across/down numbers in the grid |
| `focusBackground` | `'rgb(255,255,0)'` | background color for the cell with focus, the one that the player is typing into |
| `highlightBackground` | `'rgb(255,255,204)'` | background color for the cells in the answer the player is working on, helps indicate in which direction focus will be moving; also used as a background on the active clue |
Note that these values can be provided either via `ThemeProvider`, or directly as a `theme` property on the `Crossword` component itself. (And further, if you're not using styled-components, but want to make use of `ThemeProvider`, this library re-exports `ThemeProvider` so you can pull it from here.)
Also, several class names are applied to elements in the crossword, in case you want to apply styles that way:
| element | class name |
| -------------------------------------------------------------------- | ----------- |
| entire crossword component; encompassing grid and clues | `crossword` |
| entire crossword is correct (on same element as `crossword`) | `correct` |
| answer grid | `grid` |
| all of the clues | `clues` |
| header and clues for one direction | `direction` |
| direction header ('across' or 'down') | `header` |
| an individual clue | `clue` |
| an individual clue with a correct answer (on same element as `clue`) | `correct` |
(No class names are currently applied within the grid, as the SVG layout is _**very**_ layout-sensitive.)
## Player progress events
In addition to providing properties for styling, there are some properties to
help your application "understand" the player's progress:
| property | description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onCorrect` | callback function that fires when a player answers a clue correctly; called with `(direction, number, answer)` arguments, where `direction` is `'across'` or `'down'`, `number` is the clue number as text (like `'1'`), and `answer` is the answer itself |
| `onLoadedCorrect` | callback function that’s called when a crossword is loaded, to batch up correct answers loaded from storage; passed an array of the same values that `onCorrect` would recieve |
| `onCrosswordCorrect` | callback function that’s called when the overall crossword is completely correct (or not) |
| `onCellChange` | callback function called when a cell changes (e.g. when the user types a letter); passed the row and column and the character typed |
| `onClueSelected` | callback function called when a clue is selected; passed the direction and the “number” |
### Imperative methods
The following imperative methods can be called on a "ref" handle to the component:
| method name | parameters | description |
| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `focus()` | _(none)_ | Sets focus to the crossword component. |
| `reset()` | _(none)_ | Resets the entire crossword; clearing all answers in the grid and also any persisted data. |
| `fillAllAnswers()` | _(none)_ | Fills all the answers in the grid and calls the `onLoadedCorrect` callback with _**every**_ answer. |
| `isCrosswordCorrect()` | _(none)_ | Returns whether the crossword is entirely correct or not. |
## Background
Initially written as a replacement for `@guardian/react-crossword`, to make custom styling and puzzle-definition easier.
There are several things about the Crossword component from `@guardian/react-crossword` that are less than ideal, in my opinion:
- the styles/formatting are baked in
- semi-unrelated functionality like the "anagram helper" is baked in
- the data format for clues/answers is horrendous
This is an attempt to create a less-opinionated component that's much easier to drop in to an arbitrary React page.
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Pushpendra Singh
🤔
Amit Bansal
🐛
embeddedt
💻
Albranco
🤔
Rob McCollough
🤔
lorddaedra
🤔
Ilya Lukyanov
🤔
Richard Hoffmann
🤔
gitname
🐛
Craig
🤔
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!