VoxCSS

A CSS voxel engine. A 3D grid for the DOM. Renders HTML cuboids by stacking grid layers and applying transforms. Supports colors and textures, interactions and culling, plus shapes, areas and projections. Works with Vue, React, Svelte, or plain JavaScript.

Visit voxcss.com for docs and model examples.

Installation

npm install @layoutit/voxcss

You can also load VoxCSS directly from unpkg. Here is a minimal example:

<div id="voxcss"></div>

<script type="module">
  import { renderScene } from "https://unpkg.com/@layoutit/voxcss@latest/dist/index.js";

  renderScene({
    element: document.getElementById("voxcss"),
    camera: { interactive: true },
    scene: {
      voxels: [
        { x: 3, y: 3, z: 0 },
        { x: 3, y: 3, z: 1 }
      ],
      showFloor: true
    }
  });
</script>

Framework Components

Vue, React, and Svelte wrappers all expose the same components with identical props: <VoxCamera> controls the viewpoint (zoom, pan, tilt, rotation, perspective), while <VoxScene> receives the voxel array and manages the 3D grid and its decorations.

import { VoxCamera, VoxScene } from "@layoutit/voxcss/react";

export default function App() {
  const voxels = [{ x: 1, y: 1, z: 0, color: "#f00" }];

  return (
    <VoxCamera interactive>
      <VoxScene voxels={voxels} />
    </VoxCamera>
  );
}

API reference

VoxCamera props

• zoom, pan, tilt – translate the camera in/out, vertically, and horizontally.
• rotX, rotY – rotate around the X/Y axis.
• perspective – control CSS perspective depth (or disable it).
• interactive – enable pointer drag controls.
• invert – flip pointer drag direction.
• animate – auto-rotate the camera; accepts true, a speed number, or { axis, speed, pauseOnInteraction }.

VoxScene props

• voxels – array of voxel objects; optional (defaults to empty) to render a blank scene.
• rows, cols, depth – override the inferred bounds and explicitly set the 3D grid size.
• show-walls, show-floor – toggle structural planes.
• projection – pick "cubic" or "dimetric" presets to change the layer spacing (50/25px).
• mergeVoxels – collapse contiguous cubes into larger areas for better performance. Accepts true, false, or a number threshold. Defaults to auto-merging large scenes (>2000 voxels).

Voxel data model

Each voxel describes a single cell in the grid:

• x, y, z – required integer coordinates; x2/y2 optional for area footprints.
• shape – cube (default), ramp, wedge, or spike.
• color / texture – apply solid fills or image URLs per voxel.
• rot – rotation in degrees; ramps/wedges/spikes snap to 90° increments.

Example:

const voxels = [
  { x: 2, y: 2, z: 0, color: "#f97316" },
  { x: 3, y: 2, z: 0, shape: "ramp", rot: 90, color: "#94a3b8" },
  { x: 3, y: 3, z: 0, texture: "/example.png" }
];

Performance

VoxCSS renders everything in the DOM, so performance is determined by how many elements the browser has to manage. The engine reduces work through culling based on neighbors and camera rotation, only drawing the outer shell of the model with the faces that are actually visible.

The mergeVoxels prop can be essential: instead of rendering each cube as its own node, the engine scans each layer and groups adjacent voxels into larger rectangles in the x/y dimensions. Merging is auto-enabled for bigger scenes (over 2000 voxels) and can cut DOM size dramatically.

Loading MagicaVoxel (.vox) files

Use the built-in parser to turn a MagicaVoxel .vox binary into a voxel object and feed it to renderScene:

import { parseMagicaVoxel, renderScene } from "@layoutit/voxcss";

const rootEl = document.getElementById("voxcss")!;

fetch("/models/example.vox")
  .then((r) => r.arrayBuffer())
  .then((buffer) => parseMagicaVoxel(buffer))
  .then(({ voxels }) => {
    renderScene({
      element: rootEl,
      camera: { interactive: true },
      scene: {
        voxels,
        showFloor: true
      }
    });
  });

Made with VoxCSS

Layoutit Voxels → A CSS Voxel editor

Layoutit Terra → A CSS Terrain Generator

License

MIT.