SWORDS

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

  1. Open your puzzle's Manage page and go to Embed.
  2. Pick the options. The preview shows the result.
  3. 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/embed

Newspaper

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=111111

Small 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=small

Dark 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=18181b

Your 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.

Across
    Down

      0:00

      <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): bar on a phone. Elsewhere side when the lists fit beside the grid, else below.

      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=rounded

      accent 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=0 hides the title and author; toolbar=0 the Check, Reveal and More menus; timer=0 the timer. With all three off, the top bar goes away.
      • footer=min keeps only Report at the foot; footer=none keeps only the credit.
      • celebrate=0 skips the puzzle's ending animation; popup=0 the "Solved" popup.
      • solvedbar=1 shows 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")
      CommandWhat it does
      check-square, check-word, check-puzzleMark wrong letters.
      reveal-square, reveal-word, reveal-puzzleFill in the answer. reveal-puzzle asks first; add confirm: false to skip the question.
      clear-square, clear-word, clear-puzzleClear the current square, the current answer, or the whole grid. Checked and revealed letters stay.
      resetStart over: clear everything and the timer. It asks first; add confirm: false to skip the question.
      pause, resumePause 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-clueGo to the next or the previous clue.
      selectGo to a clue: { command: "select", num: 4, dir: "down" }. dir is "across" or "down".
      toggle-directionSwitch between Across and Down.
      focusPut the keyboard focus in the puzzle.
      expand, collapseWith 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:

      ErrorWhy
      unknown-commandThe frame does not know the command. swords:ready lists the ones it knows.
      pausedThe puzzle is paused.
      busyThe puzzle asks the solver a question.
      not-foundselect: no such clue.
      bad-argsselect: dir is not "across" or "down".

      Events

      MessageWhenWhat data holds
      swords:readyThe puzzle has loaded, or your page sent swords:hello.The state (below), and commands: the commands the frame knows.
      swords:puzzleRight after swords:ready.title, author, cols, rows, clues.
      swords:stateA letter, the clue or the timer changed. At most about 6 times a second.The state.
      swords:expandedWith start=grid: the puzzle opened or went back to the grid.expanded.
      swords:fullscreenWith 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:solvedThe puzzle is solved.secs: the time.
      swords:resultThe answer to a command.requestId, command, ok, error.
      swords:heightThe 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 fieldWhat it is
      secsThe time, in seconds.
      paused, solvedtrue or false.
      expandedfalse while start=grid shows only the grid.
      filled, totalSquares filled, and squares in all.
      clueThe current clue: num, dir, text, cells. null when there is none.
      squareThe index of the current square. Low level: it may change.
      cluesFor 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.

      OptionValuesDefaultWhat it does
      layoutauto side below bar gridautoWhere the clues go.
      cluesauto columns stackedautoAcross and Down side by side, or Across above Down. auto stacks them when columns would be narrow.
      startfull gridfullgrid shows only the grid until the solver clicks it.
      cell16 to 12056The largest size of a square, in pixels.
      keyboardauto on offautoThe 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.
      phoneinline fullscreeninlineOn 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.
      header1 01The title and author.
      toolbar1 01The Check, Reveal and More menus.
      timer1 0as toolbarThe timer.
      footerfull min nonefullThe 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.
      celebrate1 01The puzzle's ending animation.
      popup1 01The "Solved" popup.
      solvedbar1 00The "Solved!" bar with its Replay button.
      note1 01The puzzle's note, in small italics under the grid, when the puzzle has one. With 0 it is still in the More menu.
      themeauto light darkautoauto follows the solver's device.
      fontsystem serif rounded monosystemThe font of the clues and letters.
      bga color, or transparentthe theme'sThe background.
      accenta colorlight blueThe current answer, and its clue.
      cursora coloryellowThe current square.
      linea colorgreyThe grid lines and the frame around the grid.
      blocka colornear blackThe black squares.
      numbersa colorthe text colorThe small numbers in the squares.
      radius0 to 240Round corners on the grid, in pixels.
      shadow1 00A soft shadow under the grid.
      cluesize11 to 20autoThe size of the clue text, in pixels.
      headingsbold smallboldThe 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.