🚀 v2.0 — Ship a retro-future product without rolling your own design system.

111 components · 95%+ test coverage · WCAG 2.1 AA · 30 audit gates · switchable pixel ↔ linear surface

• 📦 Release notes →
• 🔁 Migrating from v1? → (TL;DR: it's npm install @pxlkit/ui-kit@2 and you're done)
• 📰 Press kit →

Overview

@pxlkit/ui-kit is a comprehensive React component library in the Pxlkit ecosystem, providing 57 retro pixel art styled components for building modern web applications with a nostalgic aesthetic. Every component follows a consistent pixel art design language with customizable color tones.

New in v1.5.0 — forwardRef wired across every interactive primitive, full accessibility pass (ARIA + focus rings + keyboard handlers), and PixelToast + PxlKitToastProvider shipped inside the kit. See the CHANGELOG for the full diff.

Installation

npm install @pxlkit/ui-kit

Peer dependencies: react ^18.2.0 || ^19.0.0 and react-dom ^18.2.0 || ^19.0.0

Import Styles

Add the stylesheet to your app entry point:

import '@pxlkit/ui-kit/styles.css';

Quick Start

import '@pxlkit/ui-kit/styles.css';
import { PixelButton, PixelCard, PixelInput } from '@pxlkit/ui-kit';

function App() {
  return (
    <PixelCard title="Welcome">
      <PixelInput label="Username" placeholder="Enter your name" />
      <PixelButton tone="green">Get Started</PixelButton>
    </PixelCard>
  );
}

Surface system — pixel ↔ linear

Every visible component accepts a surface?: 'pixel' | 'linear' prop that switches the aesthetic:

• pixel (default) — chunky 2px borders, sharp staircase pixel corners (via clip-path), offset block shadow with no blur, mono/pixel typography. The signature retro identity.
• linear — soft 1px borders, gentle rounded corners, blurred drop shadows, sans typography. Same API, modern aesthetic.

Switch one component:

<PixelButton surface="linear">Looks modern</PixelButton>

Switch a whole subtree via provider:

import { PxlKitSurfaceProvider } from '@pxlkit/ui-kit';

<PxlKitSurfaceProvider surface="linear">
  {/* every nested Pxlkit component inherits surface="linear" */}
</PxlKitSurfaceProvider>

Tone system

Components accept tone?: 'green' | 'cyan' | 'gold' | 'red' | 'purple' | 'pink' | 'neutral'. Tones map to design-token colours that respect the active theme (light/dark) and the --retro-* CSS variables — override any variable on :root or .dark to reskin every component.

Components

Layout

| Component | Description | | --- | --- | | PixelSection | Section container with pixel art border styling | | PixelDivider | Decorative divider with optional label |

Actions

| Component | Description | | --- | --- | | PixelButton | Primary button with pixel art styling and color tones | | PxlKitButton | Alternative button variant | | PixelSplitButton | Split button with dropdown action |

Data Display

| Component | Description | | --- | --- | | PixelCard | Card container with title and pixel borders | | PixelStatCard | Statistics display card | | PixelTable | Data table with pixel art styling | | PixelAvatar | User avatar component | | PixelBadge | Status/count badge | | PixelChip | Tag/chip component | | PixelTextLink | Styled text link | | PixelCollapsible | Expandable/collapsible content | | PixelCodeInline | Inline code snippet | | PixelKbd | Keyboard shortcut display | | PixelColorSwatch | Color swatch display | | PixelBareButton | Unstyled button base | | PixelBareInput | Unstyled input base | | PixelBareTextarea | Unstyled textarea base |

Inputs

| Component | Description | | --- | --- | | PixelInput | Text input with label and validation | | PixelPasswordInput | Password input with toggle visibility | | PixelTextarea | Multi-line text input | | PixelSelect | Dropdown select | | PixelCheckbox | Checkbox with pixel styling | | PixelRadioGroup | Radio button group | | PixelSwitch | Toggle switch | | PixelSlider | Range slider | | PixelSegmented | Segmented control / tab-like selector |

Feedback

| Component | Description | | --- | --- | | PixelAlert | Alert/notification banner | | PixelProgress | Progress bar | | PixelSkeleton | Loading skeleton placeholder | | PixelEmptyState | Empty state with message |

Navigation

| Component | Description | | --- | --- | | PixelTabs | Tab navigation | | PixelAccordion | Accordion / expandable panels | | PixelBreadcrumb | Breadcrumb navigation | | PixelPagination | Page pagination controls |

Overlay

| Component | Description | | --- | --- | | PixelModal | Modal dialog | | PixelTooltip | Tooltip popup | | PixelDropdown | Dropdown menu |

Toasts

| Component | Description | | --- | --- | | PixelToast | Pixel-art styled toast notification with positions, tones, icon slot | | PxlKitToastProvider | Toast context provider — exposes useToast() for imperative toasts |

Animations

| Component | Description | | --- | --- | | PixelFadeIn | Fade-in animation wrapper | | PixelSlideIn | Slide-in animation wrapper | | PixelPulse | Pulse animation wrapper | | PixelBounce | Bounce animation wrapper | | PixelTypewriter | Typewriter text effect | | PixelGlitch | Glitch animation effect | | PixelFloat | Floating animation wrapper | | PixelShake | Shake animation wrapper | | PixelRotate | Rotation animation wrapper | | PixelZoomIn | Zoom-in animation wrapper | | PixelFlicker | Flicker animation effect |

Parallax

| Component | Description | | --- | --- | | PixelParallaxLayer | Individual parallax layer | | PixelParallaxGroup | Scroll-based parallax group | | PixelMouseParallax | Mouse-tracking parallax container |

Providers

| Component | Description | | --- | --- | | PxlKitSurfaceProvider | Switch every nested component between pixel and linear surface | | PxlKitLocaleProvider | Locale context provider (supports en and tr) |

Locale / i18n utilities

| Export | Description | | --- | --- | | usePxlKitLocale() | Hook for locale-aware text transforms | | toLocaleUpper() | Locale-safe uppercase (handles Turkish İ/I) | | toLocaleLower() | Locale-safe lowercase (handles Turkish ı/i) | | buildGoogleFontsUrl() | Build Google Fonts URL with correct subset for locale | | PXLKIT_FONTS | Font configuration for Press Start 2P, Inter, JetBrains Mono | | TURKISH_CHARACTERS | Turkish character mapping reference |

Storybook

Every one of the 57 components is individually documented at storybook.pxlkit.xyz under the UI Kit / * sidebar. Each story has a Controls panel for live prop manipulation:

• Surface toggle (pixel ↔ linear) on every component
• Tone selector (7 tones)
• Size selector (sm / md / lg)
• Disabled / loading / variant states
• Real animated @pxlkit icons in slots
• Side-by-side surface comparison: Foundations / Surface / Side By Side

Turkish Locale Support

import { PxlKitLocaleProvider, usePxlKitLocale } from '@pxlkit/ui-kit';

function App() {
  return (
    <PxlKitLocaleProvider locale="tr">
      <MyComponent />
    </PxlKitLocaleProvider>
  );
}

function MyComponent() {
  const { upper } = usePxlKitLocale();
  return <span>{upper('istanbul')}</span>; // → İSTANBUL
}

Related Packages

| Package | Description | | --- | --- | | @pxlkit/core | Core rendering engine and icon components | | @pxlkit/ui | 41 UI & interface pixel art icons | | @pxlkit/gamification | 51 icons — RPG, achievements, rewards | | @pxlkit/feedback | 33 icons — alerts, status, notifications | | @pxlkit/social | 43 icons — community, emojis, messaging | | @pxlkit/weather | 36 icons — climate, moon, temperature | | @pxlkit/effects | 12 animated VFX icons | | @pxlkit/parallax | 10 multi-layer 3D parallax icons |

Documentation

Explore the full component showcase and documentation at pxlkit.xyz.

License

MIT License — code package. See the repo licensing overview for split-license scope details.

Created by Joangel De La Rosa