Embed a Swords puzzle
Put any Swords puzzle in a page of your own site. It runs in a frame (an iframe). You choose its layout and colors, and your page can send it commands and hear what the solver does.
Quick start
- Open your puzzle's Manage page and go to Embed.
- Pick the options. The preview shows the result.
- Copy the code and paste it into your page.
The code is the frame plus a short height script. The grid's size comes from the frame's width; the height follows what the frame shows, so the frame never scrolls inside.
<iframe src="https://swords.cx/p/ID/embed" title="Crossword" style="width:100%;border:0" allow="clipboard-write; web-share"></iframe>
<script>
addEventListener("message", (e) => {
if (e.origin !== "https://swords.cx" || e.data?.type !== "swords:height") return
for (const f of document.querySelectorAll("iframe")) if (f.contentWindow === e.source) f.style.height = e.data.data.height + "px"
})
</script>Every embed shows a small "Powered by swords.cx" link at its foot. It is always there, in every layout, and no option removes it.
Examples
The same puzzle, five ways. Each frame is live: try it. Copy the address and put your puzzle's ID in place of ID.
Drop-in
A blog post or an article. No options: the frame picks a layout for its width.
https://swords.cx/p/ID/embedNewspaper
A site with a print feel: serif type, black and white, square corners, the full toolbar.
https://swords.cx/p/ID/embed?layout=side&font=serif&headings=bold&theme=light&accent=e5e5e5&cursor=bdbdbd&line=111111&block=111111Small widget
A sidebar or a narrow card. Only the grid shows until someone clicks it.
https://swords.cx/p/ID/embed?start=grid&layout=below&clues=stacked&cell=34&header=0&toolbar=0&footer=none&theme=light&bg=transparent&accent=e3efe6&cursor=b7d8c0&line=c9d3cc&radius=10&cluesize=13&headings=smallDark brand theme
A dark site with its own brand colors.
https://swords.cx/p/ID/embed?theme=dark&font=rounded&accent=3b2a6b&cursor=8b5cf6&line=3f3f46&radius=8&bg=18181bYour own clues and buttons
An app or a page with its own design. The frame shows only the grid; your page draws the clue list, the buttons and the timer, and talks to the frame with messages.
<div class="xw">
<iframe id="puzzle" src="https://swords.cx/p/ID/embed?layout=grid&header=0&toolbar=0&timer=0&footer=none" title="Crossword" style="width:240px;border:0"></iframe>
<div><b>Across</b><ol id="across"></ol><b>Down</b><ol id="down"></ol></div>
</div>
<p><button data-cmd="check-word">Check word</button> <button data-cmd="reveal-word">Reveal word</button> <span id="time">0:00</span></p>
<script>
const SITE = "https://swords.cx"
const frame = document.getElementById("puzzle")
const send = (m) => frame.contentWindow.postMessage({ type: "swords:command", ...m }, SITE)
const items = {}
addEventListener("message", (e) => {
if (e.origin !== SITE || e.source !== frame.contentWindow) return
const { type, data } = e.data
if (type === "swords:height") frame.style.height = data.height + "px"
if (type === "swords:puzzle" && !Object.keys(items).length)
for (const c of data.clues) {
const li = document.createElement("li")
li.textContent = c.num + ". " + c.text
li.onclick = () => send({ command: "select", num: c.num, dir: c.dir })
document.getElementById(c.dir).append(li)
items[c.num + c.dir] = li
}
if (type === "swords:state") {
document.getElementById("time").textContent = Math.floor(data.secs / 60) + ":" + String(data.secs % 60).padStart(2, "0")
for (const c of data.clues) {
items[c.num + c.dir]?.classList.toggle("done", c.complete)
items[c.num + c.dir]?.classList.toggle("on", data.clue?.num === c.num && data.clue?.dir === c.dir)
}
}
})
// The frame may have loaded first: ask it to send the puzzle again.
frame.contentWindow.postMessage({ type: "swords:hello" }, SITE)
for (const b of document.querySelectorAll("[data-cmd]")) b.onclick = () => send({ command: b.dataset.cmd })
</script>Layout
Choose where the clues go with layout:
side: the clue lists stand beside the grid. In a frame too narrow for them (under 560 pixels, or a clue column under 260), the grid goes on top, as wide as the frame, with the lists under it. The layout changes again when the frame is resized.below: the clue lists are under the grid.bar: one clue at a time, in a bar under the grid, as on a phone.grid: the grid alone. Your page shows the clues (see Grid first, grid only).auto(the default):baron a phone. Elsewheresidewhen the lists fit beside the grid, elsebelow.
Across and Down stand side by side when each gets about 230 pixels, and stack (Across above Down) when they would be narrower. Beside the grid (layout=side), a big grid gets a little smaller to make room for the two columns, down to squares of 32 pixels; the grid alone (start=grid) keeps its full size. clues=columns or clues=stacked forces one. cell sets the largest size of a square; squares get smaller in a narrow frame.
Custom theme
theme=light or dark fixes the colors; auto follows the solver's device. Then set any color as 3 or 6 hex digits, without the #:
?theme=light&bg=transparent&accent=d6ebfa&cursor=8ebfe9&line=b8bec9&numbers=a4acb7&radius=12&font=roundedaccent colors the current answer and its clue, cursor the current square, line the grid lines, block the black squares and numbers the small numbers. bg=transparent shows your page through. radius, shadow, font, cluesize and headings do the rest; see All options.
Show or hide parts
header=0hides the title and author;toolbar=0the Check, Reveal and More menus;timer=0the timer. With all three off, the top bar goes away.footer=minkeeps only Report at the foot;footer=nonekeeps only the credit.celebrate=0skips the puzzle's ending animation;popup=0the "Solved" popup.solvedbar=1shows a "Solved!" bar with a Replay button after a solve. It is off by default.
Grid first, grid only
With start=grid the frame first shows only the grid, and the timer waits. The first click or key opens the layout you chose and starts the timer. A click elsewhere on your page goes back to the grid alone. Your page gets a new height and a swords:expanded message each time, so it can show or hide its own parts. The frame fades its parts in and out (about 0.2 seconds; not at all for solvers who ask for less motion), and it sends the new height once, at the start, so your page can let the height glide:
<style>
#puzzle { transition: height 220ms ease-out; }
@media (prefers-reduced-motion: reduce) { #puzzle { transition: none; } }
</style>
<script>
// Your own parts round the frame (here, a box with the id "card") show only while it is open.
addEventListener("message", (e) => {
if (e.origin !== "https://swords.cx" || e.data?.type !== "swords:expanded") return
document.getElementById("card").classList.toggle("open", e.data.data.expanded)
})
// A click outside the box closes the puzzle. A click inside it keeps it open.
addEventListener("pointerdown", (e) => {
const inside = document.getElementById("card").contains(e.target)
document.getElementById("puzzle").contentWindow.postMessage({ type: "swords:command", command: inside ? "expand" : "collapse" }, "https://swords.cx")
})
</script>With layout=grid the frame shows only the grid, always. Your page shows the clues: see the last example.
Control it from your page
Your page and the frame talk with postMessage. Check e.origin and e.source before you trust a message. The frame takes commands only from the page that holds it.
Every message from the frame has the same shape: { type, v: 1, id, data }. v is the version of this API, id the puzzle's ID, and data what the message holds. Ignore types and fields you do not know. Version 1 only gets new fields; a rename or a removal comes with a new v.
Any page that embeds the puzzle gets these messages, so they never hold the answers or anything secret.
Hello
The frame may load before your script listens. After you add your listener, send swords:hello; the frame sends swords:ready and swords:puzzle again.
frame.contentWindow.postMessage({ type: "swords:hello" }, "https://swords.cx")Commands
frame.contentWindow.postMessage({ type: "swords:command", command: "check-word", requestId: 1 }, "https://swords.cx")| Command | What it does |
|---|---|
check-square, check-word, check-puzzle | Mark wrong letters. |
reveal-square, reveal-word, reveal-puzzle | Fill in the answer. reveal-puzzle asks first; add confirm: false to skip the question. |
clear-square, clear-word, clear-puzzle | Clear the current square, the current answer, or the whole grid. Checked and revealed letters stay. |
reset | Start over: clear everything and the timer. It asks first; add confirm: false to skip the question. |
pause, resume | Pause or resume the timer. Pause hides the grid. An embed never pauses itself (the timer still stops while the tab is hidden); send pause when you want it. |
next-clue, prev-clue | Go to the next or the previous clue. |
select | Go to a clue: { command: "select", num: 4, dir: "down" }. dir is "across" or "down". |
toggle-direction | Switch between Across and Down. |
focus | Put the keyboard focus in the puzzle. |
expand, collapse | With start=grid: open the puzzle, or go back to the grid alone. |
A command only changes this solver's progress, in this browser. While the puzzle is paused or asks a question, only pause, resume, focus, expand and collapse work.
The frame answers each command with swords:result: requestId (yours, if you sent one), command, ok, and, when ok is false, error:
| Error | Why |
|---|---|
unknown-command | The frame does not know the command. swords:ready lists the ones it knows. |
paused | The puzzle is paused. |
busy | The puzzle asks the solver a question. |
not-found | select: no such clue. |
bad-args | select: dir is not "across" or "down". |
Events
| Message | When | What data holds |
|---|---|---|
swords:ready | The puzzle has loaded, or your page sent swords:hello. | The state (below), and commands: the commands the frame knows. |
swords:puzzle | Right after swords:ready. | title, author, cols, rows, clues. |
swords:state | A letter, the clue or the timer changed. At most about 6 times a second. | The state. |
swords:expanded | With start=grid: the puzzle opened or went back to the grid. | expanded. |
swords:fullscreen | With phone=fullscreen, on a phone or tablet in a frame under 560 pixels: the puzzle asks to be shown full screen (on: true) or is done (on: false). To accept, answer { type: "swords:fullscreen-ack" } within 0.3 seconds and make the frame cover the screen (position: fixed; inset: 0; width: 100vw; height: 100dvh). With no answer it opens in the page as usual. | on. |
swords:solved | The puzzle is solved. | secs: the time. |
swords:result | The answer to a command. | requestId, command, ok, error. |
swords:height | The frame needs a new height. | height, in pixels. |
Clue data and state
Each clue in swords:puzzle has num, dir ("across" or "down"), text, row and col (its first square), length and cells. It never holds the answers. A square's index is row * cols + col, counted from 0 at the top left.
| State field | What it is |
|---|---|
secs | The time, in seconds. |
paused, solved | true or false. |
expanded | false while start=grid shows only the grid. |
filled, total | Squares filled, and squares in all. |
clue | The current clue: num, dir, text, cells. null when there is none. |
square | The index of the current square. Low level: it may change. |
clues | For each clue: num, dir, filled and complete. Low level: it may change. |
cells (in a clue) is low level too, and may change.
Height script
The frame tells your page how tall it is with a swords:height message whenever that changes. Put this script on the page once; it sizes every Swords frame on it.
<script>
addEventListener("message", (e) => {
if (e.origin !== "https://swords.cx" || e.data?.type !== "swords:height") return
for (const f of document.querySelectorAll("iframe")) if (f.contentWindow === e.source) f.style.height = e.data.data.height + "px"
})
</script>Customize with an AI agent
An AI assistant (Claude, ChatGPT, Cursor and the like) can set up the embed for you. Copy this prompt, put in your puzzle's ID and a few words about your site, and paste it into the assistant. It asks about your page, then gives you the code. The Manage page's Embed section copies it with your ID and options filled in.
You help me embed a Swords crossword in my website. The full guide is at https://swords.cx/embed. Read it if you can.
My puzzle ID: <PUZZLE_ID>
My site: <YOUR SITE DETAILS: what it is built with, and a link or a description of the page>
First ask me what you still need to know:
- How wide the place for the puzzle is, on desktop and on phones.
- My fonts and colors, and if my site has a light mode, a dark mode or both.
- If I want the puzzle's own clue lists and buttons, or my own on my page.
- If the puzzle should start small (grid only) and open on a click.
Then give me: the iframe with its full src, the height script, and any HTML, CSS and JS my page needs. Keep it short, and explain each option you set in one line.
THE FRAME
<iframe src="https://swords.cx/p/<PUZZLE_ID>/embed?OPTIONS" title="Crossword" style="width:100%;border:0" allow="clipboard-write; web-share"></iframe>
The grid size comes from the frame width. The frame never scrolls; the page must set its height from the swords:height message:
addEventListener("message", (e) => {
if (e.origin !== "https://swords.cx" || e.data?.type !== "swords:height") return
for (const f of document.querySelectorAll("iframe")) if (f.contentWindow === e.source) f.style.height = e.data.data.height + "px"
})
OPTIONS (query parameters; a bad value falls back to the default)
layout: auto|side|below|bar|grid (auto). side = clues beside the grid, below = under it, bar = one clue at a time, grid = grid only (the page draws the clues). auto picks bar on phones, else side if it fits, else below.
clues: auto|columns|stacked (auto). auto puts Across and Down side by side when each gets about 200px, else stacks them.
start: full|grid (full). grid = only the grid until the solver clicks it; the timer waits. A click elsewhere on the page returns it to the grid.
cell: 16-120 (56), the largest square size in px
keyboard: auto|on|off (auto = touch screens only; 1 and 0 also work)
header, toolbar: 1|0 (1). timer: 1|0 (same as toolbar)
footer: full|min|none (full). full = Copy link and Report (no Copy link on a PIN puzzle); min = Report; none = neither (0 also works)
celebrate, popup: 1|0 (1). The solve animation, the "Solved" popup.
solvedbar: 1|0 (0). The "Solved!" bar with a Replay button.
note: 1|0 (1). The puzzle's note under the grid, when it has one (still in the More menu with 0).
theme: auto|light|dark (auto). font: system|serif|rounded|mono (system)
bg: a color or transparent. accent (current answer), cursor (current square), line (grid lines), block (black squares), numbers (square numbers): colors
Colors are 3 or 6 hex digits without "#", like accent=d6ebfa.
radius: 0-24 (0). shadow: 1|0 (0). cluesize: 11-20 (auto). headings: bold|small (bold)
Every embed shows a small "Powered by swords.cx" link at the foot. It is always there; do not try to hide it.
MESSAGES (postMessage, version 1)
Always check e.origin === "https://swords.cx" and e.source === frame.contentWindow before you trust a message. Send only to the origin "https://swords.cx". The frame takes commands only from the page that holds it.
Every message from the frame is { type, v: 1, id, data }. Ignore types and fields you do not know: version 1 only adds fields; a rename or removal makes a new v.
Any page that embeds the puzzle gets these messages; they never hold answers or anything secret.
After you add your listener, send { type: "swords:hello" }; the frame answers with swords:ready and swords:puzzle again (in case you missed them).
Send: frame.contentWindow.postMessage({ type: "swords:command", command: "check-word", requestId: 1 }, "https://swords.cx")
Commands: check-square, check-word, check-puzzle, reveal-square, reveal-word, reveal-puzzle, clear-square, clear-word, clear-puzzle, reset, pause, resume, next-clue, prev-clue, toggle-direction, focus, expand, collapse, and select with { num: 4, dir: "down" } (dir must be "across" or "down"). reveal-puzzle and reset ask first unless you add confirm: false.
Each command gets swords:result: { requestId, command, ok, error? } with error one of unknown-command, paused, busy (a question is open), not-found, bad-args.
The frame sends (data):
- swords:ready: the state, plus commands: the list of commands it knows.
- swords:puzzle: { title, author, cols, rows, clues: [{ num, dir: "across"|"down", text, row, col, length, cells }] }. A square's index is row * cols + col, from 0 at the top left. No answers.
- swords:state (up to ~6 a second): { secs, paused, solved, expanded, filled, total, clue: { num, dir, text, cells } | null, square, clues: [{ num, dir, filled, complete }] }. square is the cursor's index. An embed never pauses itself: send pause if you want one. square, cells and clues[] are low-level and may change.
- swords:expanded: { expanded } (with start=grid)
- swords:solved: { secs }
- swords:result: the answer to a command (above)
- swords:height: { height } in px
PATTERNS
- Own clue list: layout=grid&header=0&toolbar=0&timer=0&footer=none. Build the list from swords:puzzle, mark the current and complete clues from swords:state, and send select on a click.
- Grid first: start=grid. Show your own title or buttons only while swords:expanded says expanded. Send expand on pointerdown inside your card and collapse outside it.
- Match my site: theme, bg=transparent, font, accent, cursor, line, radius and cell.All options
Add options to the frame's address, like ?layout=side&footer=min. A value that is not on the list is ignored, and the option keeps its default.
| Option | Values | Default | What it does |
|---|---|---|---|
layout | auto side below bar grid | auto | Where the clues go. |
clues | auto columns stacked | auto | Across and Down side by side, or Across above Down. auto stacks them when columns would be narrow. |
start | full grid | full | grid shows only the grid until the solver clicks it. |
cell | 16 to 120 | 56 | The largest size of a square, in pixels. |
keyboard | auto on off | auto | The on-screen keyboard. auto: phones and tablets only (a mobile browser, an iPad, or a touch screen with no mouse or trackpad), not laptops with a touch screen. There, one clue shows at a time, in a bar between the grid and the keyboard. 1 and 0 work too. |
phone | inline fullscreen | inline | On a phone or tablet in a narrow frame. fullscreen: opening asks your page to show the frame full screen (see swords:fullscreen), with a short bar (title, timer, Check, Reveal, Close), the grid, one clue at a time and the keyboard at the foot. Close or Escape goes back. |
header | 1 0 | 1 | The title and author. |
toolbar | 1 0 | 1 | The Check, Reveal and More menus. |
timer | 1 0 | as toolbar | The timer. |
footer | full min none | full | The links at the foot: Copy link (copies the puzzle's address) and Report, Report only, or none. A puzzle with a PIN never shows Copy link, nor Copy result after a solve (0 works too). The "Powered by swords.cx" credit always stays. |
celebrate | 1 0 | 1 | The puzzle's ending animation. |
popup | 1 0 | 1 | The "Solved" popup. |
solvedbar | 1 0 | 0 | The "Solved!" bar with its Replay button. |
note | 1 0 | 1 | The puzzle's note, in small italics under the grid, when the puzzle has one. With 0 it is still in the More menu. |
theme | auto light dark | auto | auto follows the solver's device. |
font | system serif rounded mono | system | The font of the clues and letters. |
bg | a color, or transparent | the theme's | The background. |
accent | a color | light blue | The current answer, and its clue. |
cursor | a color | yellow | The current square. |
line | a color | grey | The grid lines and the frame around the grid. |
block | a color | near black | The black squares. |
numbers | a color | the text color | The small numbers in the squares. |
radius | 0 to 24 | 0 | Round corners on the grid, in pixels. |
shadow | 1 0 | 0 | A soft shadow under the grid. |
cluesize | 11 to 20 | auto | The size of the clue text, in pixels. |
headings | bold small | bold | The Across and Down headings: a newspaper head, or small grey capitals. |
Notes
- Progress is kept in the solver's browser, for each puzzle, as on the puzzle's own page.
- A puzzle with a PIN asks for it inside the frame. Some browsers do not let a frame remember it; the frame then offers a link to the puzzle's own page.
- Links in the frame open in a new tab.