Documentation / Design & UI

Pixelarticons

Installed with bun add pixelarticons. The public package provides free SVGs and typed React components; a developer can optionally upgrade their own installation to the Pro collection. Every default application import works with the public free package, so the starter requires no paid icon credential.

import { Heart } from "pixelarticons/react/Heart.js";

<Heart className="size-6 text-primary" aria-hidden="true" />

Use currentColor with semantic Tailwind color tokens. Icons inside controls should inherit their text color; use text-primary for standalone emphasis and reserve numbered accent shades for deliberate brand highlights. Prefer sizes of 24 or 48 pixels (size-6 or size-12) to keep the pixel grid crisp. Give icon-only controls an accessible label; mark decorative icons aria-hidden.

Icon browser

Open /components/icons from the website navigation. It provides name search, Default/Sharp/Solid/Glyph filters, 24px and 48px previews, and pages of 96 icons. Centered page numbers use the same Pagination controls as the component demo, with ellipses for longer collections. Select an icon for a larger preview and copyable React name, import, or usage example.

The public kit catalog uses the verified free public npm package even when a maintainer has a licensed local installation. An initialized product's catalog reads its installed collection at build time, so a product's own licensed build can include its Pro set. No generated catalog or license is committed. Rebuild after changing the product's installed package to update its browser.

All app-owned icons use direct Pixelarticons imports, including Base UI controls and toast icons. ESLint prevents new Lucide imports. components.json retains the CLI-supported Lucide mapping for registry compatibility; after adding registry components, replace their generated icons with Pixelarticons and remove any re-added Lucide dependency before committing.

Licensed installation

Set PIXELARTICONS_LICENSE_KEY in the ignored .env.local before running bun install. The postinstall script runs the official Pro upgrade and regenerates the package's React components. To upgrade an existing installation manually:

bun run icons:upgrade

Without the key, postinstall leaves the free package available. The explicit upgrade command requires the key. An attempted upgrade fails the installation if license verification or download fails. The upgrade requires network access and unzip.

The default check and release verification use the free set. Do not introduce Pro-only imports into the portable starter: a local upgraded package can hide missing imports until another developer installs it. Derived products that deliberately use Pro-only icons must supply their own installation credentials in trusted CI. Never make a kit consumer depend on the kit maintainer’s paid credentials.

Keep the key out of source and NEXT_PUBLIC_* variables. The license is needed at installation, not at runtime. A fresh package install replaces the upgraded contents, which is why the postinstall hook is necessary. The icon browser displays the installed collection; it does not offer a bulk asset download.

See the official documentation for available styles, licensing, and usage.

Portable import verification

Run bun run check:portable after changing icons. This network-enabled check resolves the exact installed Pixelarticons version, fetches public npm metadata without credentials, verifies the public tarball integrity, and checks real source imports against its file list. Downloads are cached under ignored .local/portable-icons; no package code is extracted or executed. Ordinary unit tests use fixtures and do not need network access.

The initial distribution conversion checked the public pixelarticons@2.4.1 tarball. Two Pro-only symbols were replaced with free equivalents: NotebookPen with Notebook in personal notes, and CheckboxCircle with CheckboxOn in success toasts. The same verification remains available in derived products and must pass after changing default imports or upgrading the dependency. The public kit always presents the verified free icon set; products can display their independently licensed installation.