BRiCKBOX

Give any element
real depth.

A tiny library that turns any element into a 3D slab you can tilt, press and drag. It stays real HTML.

npm i brickbox
How it works

A slab built from your element

brickbox measures your element once, draws thin walls behind it and lets CSS do the 3D. The element is the front face. It is never cloned or rewritten, so text stays selectable and buttons keep working.

At rest nothing runs. Touch it and it tilts, press it and it sinks.

Size
9.8 KB

gzipped, with no dependencies.

Real HTML
100%

your own element. Never cloned or rewritten.

Server safe
0

touches of window or document while rendering.

Quick start

Two minutes to your first slab

  1. Install it

    npm i brickbox
  2. Wrap one element

    import { BrickBox } from 'brickbox/react';
    
    <BrickBox depth={24} control="hover" tilt={{ x: 14, y: 22 }}>
      <div className="rectangle">this is a rectangle</div>
    </BrickBox>
Three rules to know
  1. Rule 1The wrapper holds exactly one element, and that element is the front face.
  2. Rule 2Layout (flex, grid, margins, position) goes on the wrapper. Looks (background, radius, padding) stay on the element.
  3. Rule 3Opacity, filter and overflow go on the wrapper, never inside it, because they flatten the 3D.
ExamplesBoxes inside boxes inside boxes
4 nested boxes + 5 parts
BRICKCAM

Brick camera

Body, lens barrel, lens ring, glass, flash, shutter and strap lugs are all separate boxes, each nested in the one below. Press the shutter.

11 pressable buttons
SRC
M
▲▼◀▶
OK
+VOL−
+CH−

Remote control

A rounded body with eleven real buttons. The D-pad is a clip-path cross with its own OK button on top, and every key sinks with pressDepth when you click it.

ignore: turnable knobs
FM 98.0
TUNE VOL
BRICK 'N' ROLL

Retro radio

Drag the two knobs. They use the ignore prop, so the radio holds still while you turn them. Tune moves the needle, volume sets how hard the speaker cone beats.

20 boxes, one scene

Robot buddy

Eyes follow your pointer, built from a box inside a box inside the head. The three chest buttons blink the eyes, light the antenna and speed up the heart.

Good to knowWhat it does, and what it doesn’t
Browser support

Tested on major browsers

Tested on desktop and phone browsers, including Firefox, Safari and older mobile browsers. Nesting (lift) is the newest feature, so it has had the least testing.

What it supports

  • Any shape: rounded rectangles, pills, circles, blobs, and clip-path outlines with holes and calc() lengths.
  • Solid or single-gradient colours, continued around the sides and kept in step as they change.
  • Soft shadows with shadow, and nested parts with lift.
  • Areas that opt out of hover, drag and press, with ignore.
  • Server rendering of the React wrapper.

What it does not do yet

  • Clip-paths that use url(#id) or shape(). An unsupported clip-path falls back to the rounded rectangle.
  • Background images, stacked backgrounds, radial or conic gradients, or stops in px or em. These fall back to a solid colour. The walls follow the background, never the border colour.
  • Extruding the element’s own box-shadow or outline. Borders stay on the front face.
  • Depth beyond about half of perspective can clip or distort. Development builds log a warning.
  • Opacity, filter and overflow must go on the wrapper, not inside it, or the 3D flattens. A nested part can’t stand out of a parent face that has them or a clip-path.
  • Known issue: when pressSink is set, a press can start, and fire :active styles, just before a drag cancels it.

It uses a small amount of JavaScript to measure the element and build the walls. It is not a CSS-only effect.

Contribute

Help us find the rough edges

Every change to brickbox is measured against six house rules. Read the contributing guide.

Quiet and gentle

Light on the page

No timers or animation loops while nobody is touching it. No layout changes, walls hidden from screen readers, reduced motion respected, and no network or storage use.

Tiny

No dependencies, no stylesheet

No runtime dependencies and no stylesheet to import. Every change is measured against six house rules, and the goal is to shrink, not grow.

Honest

Honest about limits

If something does not work, the docs say so. The limits are listed above, and the browsers that have not been checked are named.

Report a bug

Open an issue on GitHub. Say which browser and version you used, your operating system, what you expected and what you saw. A short snippet that shows it helps most.

Open an issue
Help test

Open the playground in Safari or Firefox, try hover, drag, press and a few shapes, then tell us what worked and what did not. Both good and bad reports are useful.

Contributing guide