Installation

React: install the free package

Works with React 18.2+ and 19, in Vite, Next.js, Remix and any React app. npm 7+, pnpm and bun add the peer packages for you.

npm install @pixelsds/react

# yarn 1 does not add peer packages, so list them:
yarn add @pixelsds/react react-aria-components @internationalized/date recharts react-is

Add the styles

Your app uses Tailwind CSS v4: add one line after @import "tailwindcss". It brings the tokens, fonts and dark mode, and tells Tailwind to read our components inside node_modules (Tailwind skips that folder by default).

@import "tailwindcss";
@import "@pixelsds/react/tailwind.css";

No Tailwind: import the ready-made CSS once, for example in main.jsx or app/layout.js.

import '@pixelsds/react/styles.css';

Use a component

import { Button, Input } from '@pixelsds/react';
import { ArrowRight } from '@pixelsds/react/icons';

export default function SignIn() {
  return (
    <form className="flex flex-col gap-3">
      <Input label="Email" placeholder="you@company.com" />
      <Button trailingIcon={ArrowRight}>Continue</Button>
    </form>
  );
}

Every component, pattern and template is in the Storybook with its code. Dark mode: <html data-px-theme="dark">. Right to left: <html dir="rtl" lang="ar"> plus React Aria's <I18nProvider locale="ar-AE">.

Pro: install with your licence key

Your Pixels purchase email has one licence key per developer (it starts with px_live_). Keep it secret: put it in an environment variable, never in a file you commit.

1. Save the key as PIXELS_LICENSE_KEY.
2. Add .npmrc to your project. It holds no key, so it is safe to commit.
3. Install the Pro package next to the free one.

# 1. macOS / Linux (add to ~/.zshrc or ~/.bashrc to keep it)
export PIXELS_LICENSE_KEY=px_live_your_key
# Windows PowerShell:   setx PIXELS_LICENSE_KEY px_live_your_key   (then open a new terminal)

# 2. .npmrc in your project root
@pixelsds-pro:registry=https://npm.pixelsds.com/
//npm.pixelsds.com/:_authToken=${PIXELS_LICENSE_KEY}

# 3. install
npm install @pixelsds/react @pixelsds-pro/react

/* Tailwind CSS v4 */
@import "tailwindcss";
@import "@pixelsds/react/tailwind.css";
@import "@pixelsds-pro/react/tailwind.css";

/* or, without Tailwind: import both ready-made files */
/* import '@pixelsds/react/styles.css'; import '@pixelsds-pro/react/styles.css'; */

Package managers

Frameworks

• Next.js App Router: works as is. Every component ships as a client component ('use client'), so you can import it in a server page.
• Next.js 16 with cacheComponents: date pickers, calendars and the meeting scheduler read today's date, so wrap them in <Suspense>.
• TypeScript: types are included. Every prop is optional.
• Monorepos: put .npmrc at the root; every app with Tailwind needs the @import lines in its own CSS.
• React Native and Expo: not supported (the components need the browser DOM).

CI and deploy

Builds on servers need the key too. Add PIXELS_LICENSE_KEY as a secret, never in the code.

• Vercel, Netlify, Cloudflare Pages: Project settings → Environment variables → PIXELS_LICENSE_KEY, available at build time.
• GitHub Actions: Settings → Secrets → PIXELS_LICENSE_KEY, then env: PIXELS_LICENSE_KEY: ${{ secrets.PIXELS_LICENSE_KEY }} on the install step. Pull requests from forks can't read secrets, so their install fails.
• Docker: pass the key as a build secret so it never lands in an image layer.

# Dockerfile
RUN --mount=type=secret,id=pixels,env=PIXELS_LICENSE_KEY npm ci

# build
docker build --secret id=pixels,env=PIXELS_LICENSE_KEY .

If the install fails

Leaked a key? Write to hello@pixelsds.com: we switch it off and email a new one.

Plain HTML and CSS

No build step. Download the files from this site (or copy them into your project) and link them in your page head:

<link rel="stylesheet" href="/css/pixels-tokens.css">
<link rel="stylesheet" href="/css/pixels-ui.css">
<script src="/js/pixels-ui.js" defer></script>

Add the font

Pixels uses Poppins for Latin scripts and switches to an Arabic face in RTL mode.

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&display=swap">

Scope the styles

Add px-ui to <body> (or any wrapper) to set the font, text color and box sizing for everything inside.

<body class="px-ui">
  <button class="px-btn">Save changes</button>
</body>

Icons

Examples use 24×24 stroke icons with class="px-icon". Any stroke set works (the Figma file uses a matching set). Code samples shorten the SVG paths to …; the Copy button copies the full markup.