Hexagonal grids

Drop-in CSS for hex boards and honeycomb layouts. You bring normal HTML and set a few classes and CSS variables, and the stylesheet handles where each cell sits on the grid.

Quick start

Install the package, import the styles you nee, this package offers separately:

1. Just the hexagon shape - clip an HTML element into a hexagon.
2. A hexagonal grid - place many cells using either axial coordinates ((q, r)) or an offset row/column style map, you don't have to fill it with hexagons, as long as you're trying to pack your shape in a hexagon-like way.

Take a look at Red blob Games's hex grid explainer for some of the definitions.

npm install @pcvera-puzzles/hexagonal-grids

@import "@pcvera-puzzles/hexagonal-grids/hexagon.css";
@import "@pcvera-puzzles/hexagonal-grids/axial-grid.css";
@import "@pcvera-puzzles/hexagonal-grids/offset-grid.css";

Hexagon tiles

Choose whether the hex points up (pointy-top) or has a flat top (flat-top). Put hexagon-clip on the element you want clipped and set --hex-size on an ancestor (often the same wrapper).

  <div class="pointy-top hexagon-clip" style="--hex-size: 100px;">Your content</div>

A grid of hexes

Use a relative container, add axial-grid or offset-grid, plus the same orientation class (pointy-top or flat-top). Each cell is a placed-hex; add hexagon-clip if you want the visible hex shape.

Axial - natural for algorithms and many game maps. Each cell sets --q and --r (see Red Blob Games: Hex grids for the idea behind the coordinates).

<div
  class="axial-grid pointy-top"
  style="
    position: relative;
    --hex-size: 120px;
    --gap: 4px;
    --row-count: 4;
    --col-count: 5;
  "
>
  <div class="placed-hex hexagon-clip" style="--q: 0; --r: 0;">A</div>
  <!-- more cells with different --q / --r -->
</div>

Offset - same --q / --r on each cell, but the layout matches a staggered row/column board. Add one parity class on the container:

• Pointy-top: odd-r or even-r
• Flat-top: odd-q or even-q

<div
  class="offset-grid pointy-top odd-r"
  style="
    position: relative;
    --hex-size: 120px;
    --gap: 4px;
    --row-count: 4;
    --col-count: 5;
  "
>
  <div class="placed-hex hexagon-clip" style="--q: 0; --r: 0;">A</div>
</div>

Tuning the board

These custom properties control spacing and how big the grid’s bounding box is (both grid modes use the same names):

| Property | What it does | |----------|----------------| | --hex-size | Size of each hex (required). Same meaning as for standalone hexagon-clip. | | --gap | Space between cells, in pixels. | | --row-count / --col-count | How many rows and columns the container’s width and height are calculated for. | | --x-offset-hexes / --y-offset-hexes | Slide the whole grid in “hex space” without renumbering your cells. |

Fractional counts and offsets are supported where the browser can evaluate the underlying math.

What’s in the box

| File | Use it when… | |------|----------------| | hexagon.css | Define the hex shape. | | axial-grid.css | You think in axial ((q, r)) coordinates. | | offset-grid.css | You want odd-r / even-r (pointy) or odd-q / even-q (flat) staggering. |

Import only the files you use; they are designed to work together when you need both clipping and placement.

Browser support

The offset layout uses CSS round() for row/column parity. Recent evergreen browsers handle this well; if you must support much older engines, try the axial grid first or confirm round() in your target matrix.

License

MIT - see LICENSE.