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. This can be expressed either as a property-value pair in a JSON object, or as an attribute with JSON contents.

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.
• none - shift does nothing special. In this mode, symbols can be typed, so long as they are included in data-text-characters.

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 how the cell position is advanced when typing or arrowing. With crossword style (the default), the character navigation direction changes from horizontal to vertical as described in data-text-advance-on-type. With wrap style, typing will always continue in the horizontal direction, and will also will wrap from one side of the grid to the other when typing, backspacing, or arrowing left or right.

Specifies an area to avoid when drawing text in a cell. Options:

• "top"
• "bottom"
• ""

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.

Note that the names of these classes will be directly spoken by a screenreader.

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. Five drawing styles are provided: box, dots, dash, offset, 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.

Clue numbers are the numbers that go in the upper left corner of crossword cells, KenKen cells, etc.

This property has three formats:

• nothing - no cells will have clue numbers.
• crossword - clue numbers are provided everywhere a crossword would typically have one. This supports American crosswords, barred crosswords, cryptic crosswords, etc.
• all - all cells will have clue numbers.

If the puzzle contains an element with a class of crossword-clues across or crossword-clues down, li clues within an ol element will be synchronized with the clue numbers.

Clue indicators are the text (usually numbers) that go in the upper left corner of crossword cells, KenKen cells, etc.

This property has two formats:

• "" - clues are numbered sequentially.
• Any set of values (numeric or otherwise), with spaces in between.

Specifies the position of the clue labels for inner cells, whether they are automatically generated by data-clue-locations or specfically provided by data-clue-indicators.

Valid values:

• "top-left"
• "top-right"
• "bottom-left"
• "bottom-right"
• "top"
• "bottom"
• "" or "none" to suppress showing the link ID label

To specify the positions for multiple clue labels in a cell, use | characters between the positions.

Specifies clues along the top of the puzzle. Clues for each column are separated by | characters, and multiple clues per column are separated by spaces.

Specifies clues along the bottom of the puzzle. Clues for each column are separated by | characters, and multiple clues per column are separated by spaces.

Specifies clues along the left of the puzzle. Clues for each row are separated by | characters, and multiple clues per column are separated by spaces.

Specifies clues along the right of the puzzle. Clues for each row are separated by | characters, and multiple clues per column are separated by spaces.

Specifies a set of link IDs for all cells not marked with @ in the data-text field. Two cells with the same link ID anywhere on the page will share their values. The format for data-links is a set of IDs with spaces between them. IDs are applied in order to the cells, skipping cells marked with @.

Link IDs are shown in cells according to the data-link-position field. Multiple values can be shown in each cell; separate the individual values for each cell with the | character, and specify multiple positions in the data-link-position field (see that section for an example).

Note that data-extracts is a similar property that uses a separate ID space and provides highlighting. It is perfectly valid for a single cell to use both.

Specifies the position of the link ID labels in the data-links field.

Valid values:

• "top-left"
• "top-right"
• "bottom-left"
• "bottom-right"
• "top"
• "bottom"
• "" or "none" to suppress showing the link ID label

To specify the positions for multiple link ID labels in a cell, use | characters between the positions.

Specifies a set of extract codes for all cells marked with a # in the data-text field. Two cells with the same code anywhere on the page will share their values, permitting the extraction of letters from a puzzle into an answer phrase.

The format for data-extracts is a set of codes, with spaces between them. Each code is applied to the next occurrence of #.

Link IDs are shown in cells according to the data-extract-position field. Multiple values can be shown in each cell; separate the individual values for each cell with the | character, and specify multiple positions in the data-extract-position field (see that section for an example).

Note that data-links is a similar property that uses a separate ID space and does not provide highlighting. It is perfectly valid for a single cell to use both.

Specifies the position of the extract labels in the data-extracts field.

Valid values:

• "top-left"
• "top-right"
• "bottom-left"
• "bottom-right"
• "top"
• "bottom"
• "" or "none" to suppress showing the link ID label

To specify the positions for multiple extract labels in a cell, use | characters between the positions.

Specifies whether a dragging operation will continue to paint cells with the fill from the cell that was originally clicked.

Specifies whether a dragging operation will draw an interior path between cells.

Specifies whether a dragging operation will draw an exterior edge between vertices.

When edge drawing is available, a new focus model is added to support the vertices. If cell focus and vertex focus are both available, you can switch between the two models by pressing the . key.

Specifies whether a dragging operation will draw spokes between cells.

Specifies whether cells with original contents are selectable with bounding boxes or not.

Specifies a set of classes that can be used to provide extra formatting for cells. This formatting will not be editable by the solver.

Note that the names of these classes will be directly spoken by a screenreader.

Specifies a class provided by data-extra-style-classes. for each cell. There are two types of values that can be specified per character:

• . - A cell that has no extra formatting.
• any digit - A zero-based index into data-extra-style-classes that specifies the class to be placed on the cell.

data-extra-styles 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.

Turns off all mouse and keyboard input for the puzzle. Useful for solutions, samples, and scenarios with multiple puzzle layers on top of each other.

Turns off all screenreader support and leaves a screenreader message saying that this specific puzzle is not suppoerted in a screenreader. Use this option when you are doing something so special that the screenreader will not properly communicate the puzzle. Note that any puzzle options that do not yet have full screenreader support will also cause the puzzle to generate this message.

Displays buttons below the puzzle, allowing for discovery of all the features provided by the interactive solver. The About button in particular shows mouse and keyboard controls for all behaviors permitted by the options chosen.

Specifies a prompt to show to confirm clearing the puzzle when the Reset button is pressed. The text of this option is shown in the dialog. Set to "" to suppress showing a prompt.

Allows for a specifically-named identifier to be used for the puzzle, both for saved state in localStorage and for co-op scenarios. When not present, the identifier will be constructed from the page and the index of the puzzle among all .puzzle-entry objects on the page. When needed, the page portion of the identifier will be either the data-puzzle-page-id property of the body element, or if that is not present the window.location.pathname of the page.

Allows for a specifically-named identifier to be used for the team, to facilitate co-op scenarios. This can be set programmatically, and can be left blank if the whole world is on the same team.

Allows for a specifically-named identifier to be used for the team member, to facilitate co-op scenarios. This can be set programmatically, and can be left blank if no player-specific information is needed.