@guardian/react-crossword

A standalone React component for rendering crosswords.

Features

• Renders crossword grid and clues
• Displays separators in grid for hyphenated and multiple-word answers
• Layout is responsive (and can be customised)
• Attempted clues are greyed out in the clue list
• Clicking on a clue highlights the associated row or column
• Groups clues together when they span multiple columns or rows
• Progress is saved to local storage
• Answers can be checked and revealed
• Smart clearing when checking answers that strikes through incorrect letters
• Anagram helper
• Accessible: elements in the crossword are clearly labelled to communicate context and state to assistive technology
• Keyboard navigable: you can tab between the grid, clues and controls, and these can be navigated with the arrow key
• Includes print styles
• Includes support for theming and custom colour schemes

API

Props

| Prop | Details | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | data | (Required) Data to render the crossword, including clues, answers and metadata (See Crossword data format) | | progress | (Optional) Current state of the grid (See Progress format) | | Layout | (Optional) Allows default layout to be customised (See Layout) |

Any of the keys from the default theme can also be passed as a prop to customise the appearance of the crossword. These are detailed in the Theming section.

Crossword data format

This is an example set of data used to create the crossword shown above:

{
	id: 'crosswords/example/1',
	number: 1,
	name: 'Example crossword No 1',
	creator: {
		name: 'James',
		webUrl: 'https://www.theguardian.com/profile/maskarade',
	},
	date: 1740149419743,
	webPublicationDate: 1740149419743,
  entries: [
    {
      id: '1-across',
      number: 1,
      humanNumber: '1',
      clue: 'Toy on a string (2-2)',
      direction: 'across',
      length: 4,
      group: ['1-across'],
      position: { x: 0, y: 0 },
      separatorLocations: {
        '-': [2],
      },
      solution: 'YOYO',
    },
    {
      id: '2-across',
      number: 2,
      humanNumber: '2',
      clue: 'Have a rest (3,4)',
      direction: 'across',
      length: 7,
      group: ['2-across'],
      position: { x: 0, y: 2 },
      separatorLocations: {
        ',': [3],
      },
      solution: 'LIEDOWN',
    },
    {
      id: '1-down',
      number: 1,
      humanNumber: '1',
      clue: 'Colour (6)',
      direction: 'down',
      length: 6,
      group: ['1-down'],
      position: { x: 0, y: 0 },
      separatorLocations: {},
      solution: 'YELLOW',
    },
    {
      id: '3-down',
      number: 3,
      humanNumber: '3',
      clue: 'Bits and bobs (4,3,4)',
      direction: 'down',
      length: 7,
      group: ['3-down', '4-down'],
      position: { x: 3, y: 0 },
      separatorLocations: {
        ',': [4],
      },
      solution: 'ODDSAND',
    },
    {
      id: '4-down',
      number: 4,
      humanNumber: '4',
      clue: 'See 3 down',
      direction: 'down',
      length: 4,
      group: ['3-down', '4-down'],
      position: {
        x: 6,
        y: 1,
      },
      separatorLocations: {},
      solution: 'ENDS',
    },
  ],
  solutionAvailable: true,
  dateSolutionAvailable: 1542326400000,
  dimensions: {
    cols: 13,
    rows: 13,
  },
  crosswordType: 'quick',
	pdf: 'https://crosswords-static.guim.co.uk/gdn.quick.20250221.pdf',
}

Progress format

Grid progress is stored as a simple 2 dimensional array and is persisted in local storage. Each element in the array contains the value of the corresponding grid cell. Cells that are empty or not part of an answer are represented as an empty string.

The example crossword above is represented as:

[
	['Y', 'E', 'L', 'L', 'O', 'W', ''],
	['O', '', 'I', '', '', '', ''],
	['Y', '', 'E', '', '', '', ''],
	['O', 'D', 'D', 'S', 'A', 'N', 'D'],
	['', '', 'O', '', '', '', ''],
	['', '', 'W', '', '', '', ''],
	['', 'E', 'N', 'D', 'S', '', ''],
];

The data is indexed by column (x) and then row (y) so the data in the array when printed is transposed when compared to the visual layout of the grid.

For example, the last letter of 2 across is in the 7th column and 3rd row of the grid so would be accessed as progress[6][2] giving us 'N'.

Theming

The following keys from the crossword theme can be passed to the Crossword component to customise its appearance:

| Key | Description | | --------------------------------- | ------------------------------------------------------------------------- | | gridBackgroundColor | background colour of 'black' squares/dividers etc on the grid | | gridForegroundColor | background colour of 'white' squares on the grid | | gridTextColor | colour of text in the grid (clue numbers and entered letters) | | gridPrintBackgroundColor | background colour of 'black' squares on grid when printed | | gridGutterSize | size of the gap between grid cells | | gridCellSize | length of one side of a cell on on the grid | | gridCellStrikeThrough | colour of the strike through on an incorrect cell | | textColor | main text colour (grid text, clues etc.) | | focusColor | colour of the currently selected cell border | | selectedTextColor | colour of currently selected clue | | selectedBackgroundColor | colour of cells / clues that are currently selected | | connectedBackgroundColor | colour of cells / clues that are connected to the currently selected clue | | buttonBackgroundColor | background colour of clue-helper buttons | | buttonBackgroundHoverColor | hover colour of clue-helper buttons | | borderColor | border colour used to visually separate parts of the UI | | clueListBorderColor | border colour applied to the top of the clue lists | | clueMinWidth | minimum width of a clue | | clueMaxWidth | maximum width of a clue | | anagramHelperBackgroundColor | background colour of the anagram helper | | anagramHelperCandidateTextColor | text colour of shuffled letter that are not yet on the grid | | focusedClueBackgroundColor | background colour for the focused clue |

Architecture

Layout

A custom layout component can passed to the Crossword component via the Layout prop. The individual components that the crossword is composed of are passed to the layout as props so that additional elements or styles can be applied as required. (This is used in DCR to customise the layout and allow the insertion of ad slots.)

This is a simplified example of a layout:

const Layout: CrosswordProps['Layout'] = ({
	Grid,
	Clues,
	Controls,
	SavedMessage,
	AnagramHelper,
	FocusedClue,
}) => {
	return (
		<div>
			<AnagramHelper />
			<div>
				<FocusedClue />
				<Grid />
				<FocusedClue />
				<Controls />
				<SavedMessage />
			</div>

			<div>
				<Clues direction="across" />
				<Clues direction="down" />
			</div>
		</div>
	);
};

Installation

$ pnpm add @guardian/react-crossword

or

$ npm i @guardian/react-crossword