Pharos

A pixel "display" font for React: each character is a glyph drawn on a 12×18 grid and rendered as a field of squares. Serif glyphs, with vertical zones for accents, ascenders, x-height and descenders.

Installation

npm install @skvggor/pharos

Usage

import { PixelText } from "@skvggor/pharos";
import "@skvggor/pharos/styles.css";

export function App() {
  return <PixelText text="HELLO" pixelSize={14} gap={2} color="#16a34a" />;
}

PixelText props

| Prop | Type | Default | Description | | -------------------- | ------------------ | -------------- | --------------------------------------------------------------------- | | text | string | — | Text to render (required). | | pixelSize | number \| string | 6px | Size of each pixel cell. | | gap | number \| string | 1px | Gap between pixels. | | letterSpacing | number \| string | 0.5 cell | Gap between characters (accepts negative values to tighten). | | color | string | currentColor | Lit pixel color. | | offColor | string | transparent | Unlit pixel color. | | pixelShape | PixelShape | dot | Pixel shape: dot, squircle, diamond, ring, square. | | smartCorners | boolean | false | Round outer corners by neighbour analysis (square/squircle only). | | smoothness | number | 0.6 | Rounding strength (0 retro → 1 organic). | | proportional | boolean | true | Trim per-glyph side-bearing (tight kerning). false = monospace. | | spaceWidth | number | 4 | Space character width, in cells. | | renderOff | boolean | true | Render unlit cells too (needed to animate them); false = lighter DOM. | | fluid | boolean | false | Width follows the parent; height keeps the aspect ratio. | | gapRatio | number | 0.16 | Pixel gap as a fraction of the pixel (fluid mode). | | letterSpacingRatio | number | 0.5 | Letter gap as a fraction of the pixel (fluid mode). | | registry | GlyphRegistry | global | Isolated glyph registry to render from (see Isolated registries). |

Kerning

By default (proportional), each glyph is trimmed of its empty side columns and rendered at its real ink width, with a small, even gap between letters — instead of the wide, uneven spacing of a monospace canvas. The gap is adjustable through letterSpacing (and letterSpacingRatio in fluid mode), including negative values to overlap letters. Use proportional={false} for a classic monospace display look.

Fluid width

In fluid mode the component becomes a container query context (container-type: inline-size) with width: 100%, and the pixel size becomes calc(100cqw / units). Because gaps and spacing are fractions of the pixel, everything scales together — the width fills the parent and the height follows to keep the aspect ratio, with no runtime measurement.

<div style={{ width: "100%" }}>
  <PixelText text="HELLO" fluid color="#fbbf24" />
</div>

Per-pixel animation

Every pixel (lit and unlit) is rendered as a DOM element. Each lit pixel exposes CSS variables so it can be animated individually:

• --ph-i: sequential index of the lit pixel across the whole text.
• --ph-n: total number of lit pixels.
• --ph-row / --ph-col: pixel position within the character matrix.

Sweep example:

.my-class .pharos__pixel--on {
  animation: light-up 1.6s ease-in-out infinite alternate;
  animation-delay: calc(var(--ph-i) * 28ms);
}

@keyframes light-up {
  from { opacity: 0.1; transform: scale(0.6); }
  to   { opacity: 1;   transform: scale(1); }
}

Canvas metrics (12×18)

| Rows | Zone | | ----- | -------------- | | 0–2 | Accent | | 3–13 | Cap body | | 6–13 | x-height | | 14–17 | Descender |

Glyphs are authored as compact string matrices: # lit, . empty, and the numpad-mnemonic markers 7 9 1 3 for corner triangles (subpixel smoothing).

Character set

• Letters A–Z and a–z, digits 0–9.
• Accents á à â ã ä é è ê í î ó ô õ ú ü ñ ç (plus the matching capitals).
• Punctuation , . ! ? : ; - ' " ( ) / @ and space.

Use getCharacters() to list everything available. Accented glyphs are composed from a base letter plus a diacritic mark, so adding more is cheap.

Extending glyphs

Register your own glyphs (or override existing ones) at runtime. The source is validated against the canvas metrics and the cache is invalidated:

import { registerGlyph } from "@skvggor/pharos";

registerGlyph("€", [
  "............",
  "............",
  "............",
  "....#####...",
  "...##.......",
  "...##.......",
  ".#######....",
  "...##.......",
  ".#######....",
  "...##.......",
  "...##.......",
  "...##.......",
  "....#####...",
  "............",
  "............",
  "............",
  "............",
  "............",
]);

Isolated registries

registerGlyph mutates a process-wide glyph table. When that global state is a problem — SSR, tests, or two parts of an app that need different glyph sets — create an isolated registry and pass it to PixelText:

import { createGlyphRegistry, PixelText } from "@skvggor/pharos";

const registry = createGlyphRegistry();
registry.registerGlyph("€", euroSource);

<PixelText text="10€" registry={registry} />;

Each registry starts from a copy of the built-in glyphs and keeps its own parse cache, so registrations never leak across instances.

Missing glyphs

Unknown characters fall back to a blank space. The spacer is tagged with pharos__space--fallback, so you can surface gaps in your character set:

/* highlight missing glyphs while developing */
.pharos__space--fallback {
  outline: 1px dashed #f00;
}

Development

npm run dev            # visual demo
npm test               # tests
npm run test:coverage  # tests + coverage
npm run build          # build the library + types
npm run build:demo     # build the demo (GitHub Pages)

The demo is deployed to GitHub Pages from main via GitHub Actions (.github/workflows/deploy.yml).