Puzzle.js Reference: Options

The starting text for the puzzle cells. data-text can be any of the following:

• A rectangular area, e.g. 9x9 makes a blank Sudoku-size grid.
• A series of lines separated by | characters.
• If the option is specified in JSON, an array of strings, one string per line.

Characters are written into the puzzle cells, with the following characters getting special treatment:

• . - an editable blank cell
• # - an editable extract cell (see data-extracts for more information)
• @ - an uneditable black cell

A cell can also be given contents that are larger than a single character, using data-text-replacements.

A way to replace a single character in the data-text option with a string of any length.

Currently, the only way to specify this option is with a JSON object using its key-value features.

The set of valid characters that can be provided in text input. Set it to "" to reject all text input.

Sets shift key behavior when typing letters. There are two types of behavior:

• rebus - the character is appended to the cell. Useful for typing words in crossword puzzle cells, etc.
• candidates - the character is deleted if it is already present in the cell and appended otherwise. Useful for marking candidate digits in sudoku cells, etc.

Acts as if the Shift key is always pressed, yielding data-text-shift-key behavior on every keystroke even if Shift is not actually pressed.

Provides a string of characters forming the solution for the puzzle. Useful when the data-text option includes special characters that otherwise make it impossible to put the entire solution there.

data-text-solution can be any of the following:

• A series of lines separated by | characters.
• If the option is specified in JSON, an array of strings, one string per line.

Specifies whether the cell advances/retreats when typing and/or pressing backspace. When set, clicking a cell or pressing Space changes the character navigation direction from horizontal to vertical (unless there is only one row or column of text).

Specifies a set of classes that can be used to provide background fills for cells. By default, clicking a cell will cycle through these classes.

Specifies a background fill for each cell based on the classes provided by data-fill-classes. There are two types of values that can be specified per character:

• . - A cell whose fill class can be changed by the player. The starting fill class for the cell will be the first one specified in the data-fill-classes option.
• any digit - A zero-based index into data-fill-classes that specifies the unchangeable (i.e. given) fill class to be placed on the cell.

data-fills can be any of the following:

• A series of lines separated by | characters.
• If the option is specified in JSON, an array of strings, one string per line.

Specifies whether click/spacebar on a cell will cycle through the available fills specified in data-fill-classes. The default behavior is to cycle, but the pathpaint mode does not use the cycling behavior.

Specifies a set of interior paths between cells.

data-paths can be any of the following:

• A series of lines separated by | characters.
• If the option is specified in JSON, an array of strings, one string per line.

data-paths also has two types of specification:

• An m by n grid where the path segments inside each cell are specified in binary: for each cell, 1 for top, 2 for bottom, 4 for left, and 8 for right.
• A (2m+1) by (2n+1) grid where the path segments are represented by - and | segments between the cell centers. The | can also be written as l or I to make the format compatible with the lines-separated-by-| syntax. Characters at the centers and vertices are ignored, so you can type characters there that enhance the readability.

Specifies the maximum number of path directions that can emanate from a cell. If left blank, then all directions are allowed. If the value is 1, then cells can be paired but longer chains will not be possible. If the value is 2, then chains of any length can be drawn. All other numeric values are also allowed, if you have a use for them.

Specifies the way the path is drawn. Three drawing styles are provided: straight, curved, and track.

If the value ends in .svg, it is assumed to be a custom svg file for rendering paths and the svg is located with a file path relative to the puzzle page. See more information in the Styling Reference.

Specifies a set of exterior edges between cells.

data-edges can be any of the following:

• A series of lines separated by | characters.
• If the option is specified in JSON, an array of strings, one string per line.

data-edges also has two types of specification:

• A rectangular area that repeats boxes of that size, e.g. 3x3 makes 3x3 boxes for a Sudoku grid.
• An m by n grid where the path segments inside each cell are specified in binary: for each cell, 1 for top, 2 for bottom, 4 for left, and 8 for right.
• A (2m+1) by (2n+1) grid where the edge segments are represented by - and | segments between the cell centers. The | can also be written as l or I to make the format compatible with the lines-separated-by-| syntax. Characters at the centers and vertices are ignored, so you can type characters there that enhance the readability.

Specifies the way the edges and bounding box are drawn. Four drawing styles are provided: box, dots, dash, and none.

If the value ends in .svg, it is assumed to be a custom svg file for rendering edges and the svg is located with a file path relative to the puzzle page. See more information in the Styling Reference.

Specifies an initial set of spokes between cells.

data-spokes can be any of the following:

• A series of lines separated by | characters.
• If the option is specified in JSON, an array of strings, one string per line.

Either way, the lines must represent a (2m+1) by (2n+1) grid where the centers are represented by any character (though * is a good idea) and spoke segments are represented by:

• - for horizontal lines.
• |, l, or I for vertical lines. Note that | is incompatible with the lines-separated-by-| syntax.
• \ or ` (backwards single quote) for NW/SE lines. Note that \ is an escaping character and not recommended since it would really need to be typed twice and thus messes with all the alignment.
• / or ' (forwards single quote) for NE/SW lines.
• X or x for both diagonal lines.

Specifies the maximum number of spokes that can emanate from a cell. If left blank, then all directions are allowed. If the value is 1, then cells can be paired but longer chains will not be possible. If the value is 2, then chains of any length can be drawn. All other numeric values are also allowed, if you have a use for them.

Limits the directions spokes can be drawn from. The default value of * allows all directions. If a value of + is used, only cardinal directions are allowed. If a value of x is used, only diagonal directions are allowed.

The amount of different types of spokes to cycle through each time a spoke is drawn, similar to the way data-fill-cycle operates. The default value of 1 draws a single spoke and then erases it when drawn again. The value of 2 will draw over a single spoke with a double spoke, which is provided in the default spoke svg files, then erases it when drawn over again. Up to 15 levels are supported, but anything beyond the cardinal directional double spokes require custom svg files.

Specifies the way the spokes are drawn. Two drawing styles are provided: solid and dash.

If the value ends in .svg, it is assumed to be a custom svg file for rendering spokes and the svg is located with a file path relative to the puzzle page. See more information in the Styling Reference.

Breaking Changes

data-state-key has been renamed to data-puzzle-id since it is now used for multiple scenarios.