React Pixel UI - CSS Pixel Art Library for React

Pixel Size6px

Get Started

Installation

# npm
npm install @react-pixel-ui/react

# pnpm
pnpm add @react-pixel-ui/react

# yarn
yarn add @react-pixel-ui/react

Requires React 18+. @react-pixel-ui/core is installed automatically.

Primary API

<Pixel> — Wrap any element

Wrap any element and its CSS is automatically converted to pixel art. Works with inline styles, Tailwind, CSS modules.

Original CSS

Normal div

Wrapped with <Pixel>

Pixel Art!

import { Pixel } from '@react-pixel-ui/react';

<Pixel size={6}>
  <div style={{
    background: 'linear-gradient(135deg, #ff6b6b, #4ecdc4)',
    borderRadius: 24,
    border: '4px solid #333',
  }}>
    Pixel Art!
  </div>
</Pixel>

Hook API

usePixelRef — Ref-based

For maximum flexibility. Attach to any element without a wrapper.

usePixelRef

const pixelRef = usePixelRef({ pixelSize: 6 });

<div
  ref={pixelRef}
  style={{
    background: 'linear-gradient(135deg, #fd79a8, #e84393)',
    borderRadius: 20,
    border: '3px solid #b8256e',
  }}
>
  Content
</div>

Color

oklch, hsl, and translucency

Full RGBA alpha preserved end-to-end. Any CSS color form (including CSS Color 4 oklch()) works in gradients and borders.

oklch gradient

oklch + hsl

Translucent fade

RGBA preserved

Interactive

Playground

Pixel Size: 6pxBackgroundBorder Radius: 20pxBorder Width: 3pxBorder ColorWidth: 300pxHeight: 120pxShadow X: 4pxShadow Y: 4pxShadow Color

<Pixel size={6}>
  <div style={{
    background: 'linear-gradient(135deg, #ff6b6b, #4ecdc4)',
    borderRadius: 20,
    border: '3px solid #2d3436',
    width: 300,
    height: 120,
    boxShadow: '4px 4px 0 #2d3436',
  }}>
    Content
  </div>
</Pixel>

Gallery

Showcase

Card

Purple

Pink

Dark

Ocean

Sunset

Warm

Sky

Components

PixelButton

Documentation

Usage Guide

1. Basic Usage

Wrap any element with <Pixel>. It reads computed CSS and converts background, border-radius, border, and box-shadow to pixel art.

import { Pixel } from '@react-pixel-ui/react';

<Pixel size={6}>
  <div className="your-existing-classes">
    Works with Tailwind, CSS modules, inline styles
  </div>
</Pixel>

2. Hook API

Use usePixelRef when you need a ref-based approach without wrapping.

import { usePixelRef } from '@react-pixel-ui/react';

function MyComponent() {
  const ref = usePixelRef({ pixelSize: 6 });

  return (
    <div ref={ref} style={{
      background: 'linear-gradient(135deg, #fd79a8, #e84393)',
      borderRadius: 20,
      border: '3px solid #b8256e',
    }}>
      Content
    </div>
  );
}

3. Global Config

Set defaults for all <Pixel> and usePixelRef instances.

import { PixelConfigProvider } from '@react-pixel-ui/react';

<PixelConfigProvider config={{ pixelSize: 6 }}>
  <App />
</PixelConfigProvider>

4. Explicit Components

PixelBox and PixelButton take explicit props instead of reading CSS.

import { PixelBox } from '@react-pixel-ui/react';

<PixelBox
  width={280}
  height={120}
  pixelSize={6}
  borderRadius={16}
  borderWidth={3}
  borderColor="#333"
  background="linear-gradient(45deg, #ff6b6b, #4ecdc4)"
/>

Guide

When to use what

Use caseAPIWhy

Existing styled elements<Pixel>Reads CSS automatically, zero config

Third-party componentsusePixelRefAttach via ref, no wrapper div

Full manual controlPixelBoxExplicit props, no CSS reading

Quick buttonsPixelButtonReady-to-use variants

Help

FAQ

Gradient looks smooth, not pixelated?

Increase pixelSize. At size 2, blocks are 2x2 CSS pixels — too small on Retina screens. Try 6 or higher.

Does it work with Tailwind CSS?

Yes. <Pixel> reads getComputedStyle which resolves Tailwind classes into final CSS values. Just wrap your element.

What CSS properties are converted?

background, background-image (linear/radial/repeating gradients), border-radius, border, box-shadow. Other properties (color, font, padding) are preserved as-is.

Is it SSR / Next.js compatible?

Yes. Core uses pure math (no Canvas/DOM). Elements render normally on the server and pixelate after hydration.

TypeScript support?

Fully typed. Import types: PixelArtConfig, PixelShadowConfig, BorderRadii, etc.

Under the hood

How it works

Auto-detection

getComputedStyle reads your CSS. Tailwind, inline, CSS modules — all work.

Staircase Corners

clip-path: polygon() via Bresenham circle algorithm.

Pixel Gradients

Compressed RGBA PNG with staircase borders baked in + image-rendering: pixelated.

Hard Shadows

drop-shadow(blur=0) follows the clip-path contour.

Live Updates

MutationObserver + ResizeObserver track style changes.

SSR Compatible

Pure math. Zero browser APIs in core.