Handheld Device

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add handheld-device

Usage#

import { Power } from "@phosphor-icons/react"
import {
  HandheldDevice,
  HandheldDeviceBrand,
  HandheldDeviceGrille,
  HandheldDeviceKey,
  HandheldDeviceKeys,
  HandheldDeviceScreen,
  HandheldDeviceScreenBody,
  HandheldDeviceScreenFooter,
  HandheldDeviceScreenHeader,
} from "@/components/ui/handheld-device"

export function Pager() {
  return (
    <HandheldDevice>
      <HandheldDeviceGrille />
      <HandheldDeviceScreen>
        <HandheldDeviceScreenHeader>
          <span>Page</span>
          <span>21:42</span>
        </HandheldDeviceScreenHeader>
        <HandheldDeviceScreenBody className="text-2xl">CALL 4471</HandheldDeviceScreenBody>
        <HandheldDeviceScreenFooter>Press OK to clear</HandheldDeviceScreenFooter>
      </HandheldDeviceScreen>
      <HandheldDeviceKeys>
        <HandheldDeviceKey label="OK">
          <Power weight="bold" />
        </HandheldDeviceKey>
      </HandheldDeviceKeys>
      <HandheldDeviceBrand>Koala</HandheldDeviceBrand>
    </HandheldDevice>
  )
}

The shell stacks its parts in a column, and every part can be left out: a pager is a screen and a key, a scanner is LEDs and a sensor pad. Size the shell with className (w-80 by default, its height from its content); HandheldDeviceBrand sinks to the bottom of a shell taller than its parts. Everything is presentational: your app owns the state machine (idle, measuring, result) and the parts paint it.

Anatomy#

import {
  HandheldDevice,
  HandheldDeviceBrand,
  HandheldDeviceGrille,
  HandheldDeviceKey,
  HandheldDeviceKeys,
  HandheldDeviceLed,
  HandheldDeviceLeds,
  HandheldDeviceMeter,
  HandheldDevicePrinter,
  HandheldDeviceReadout,
  HandheldDeviceReceipt,
  HandheldDeviceScreen,
  HandheldDeviceScreenBody,
  HandheldDeviceScreenFooter,
  HandheldDeviceScreenHeader,
  HandheldDeviceSensor,
} from "@/components/ui/handheld-device"

<HandheldDevice>
  <HandheldDeviceGrille />
  <HandheldDeviceScreen>
    <HandheldDeviceScreenHeader />
    <HandheldDeviceScreenBody>
      <HandheldDeviceReadout />
      <HandheldDeviceMeter value={…} />
    </HandheldDeviceScreenBody>
    <HandheldDeviceScreenFooter />
  </HandheldDeviceScreen>
  <HandheldDeviceLeds>
    <HandheldDeviceLed />
  </HandheldDeviceLeds>
  <HandheldDeviceKeys>
    <HandheldDeviceKey />
  </HandheldDeviceKeys>
  <HandheldDeviceSensor />
  <HandheldDeviceBrand />
  <HandheldDevicePrinter>
    <HandheldDeviceReceipt />
  </HandheldDevicePrinter>
</HandheldDevice>

Tones#

HandheldDeviceScreen takes tone: green (the default phosphor, ready or ok), yellow (attention, a new record), orange (a read error) and red (an alarm, a positive). The tone is an ink variable that cascades: every line on the screen glows in it, and a header, a body, a footer or a readout can take its own over it.

Faults#

fault makes the picture fail while the bezel holds still. flicker is a loose contact: the picture dips a few times every second and a half. glitch is a broken panel: it jumps, skews and drops out, its color swims, and torn bands run across it. Under reduced motion both hold still, and a broken panel keeps its bands, so the fault still reads.

Readouts#

HandheldDeviceReadout is a run of lit text anywhere on the device. It takes a tone of its own, blink for the busy signal, inverse for a lit cell with the text knocked out of it (the LCD's highlight), and dim for a backlight that is off. It is a <span>; asChild renders your own element instead.

Block meter#

HandheldDeviceMeter draws the bar an LCD can: [█████─────] over the percentage, from a value of 0 to 100 (blocks cells, 10 by default). Its size is the text size you give it. To assistive tech it is a meter named by label, and the drawing is hidden.

LEDs and keys#

HandheldDeviceLed is a lens with its label printed under it: off it is dark with a hint of its tone, lit it glows, and blink pulses it. HandheldDeviceKey is a real <button> with an engraved label under it, which also names it. primary is the big round key (64px), secondary the small slate one (56 by 44); both press in and give a little (static keeps them from giving). A tone lights the glyph, the way an armed key glows.

Sensor pad#

HandheldDeviceSensor is a press-and-hold pad: a recessed glass with a glyph (its svg child, sized for you). It reports the hold through onPressStart and onPressEnd: a pointer going down and coming up, sliding off the pad (the way lifting a finger off a reader does), Space or Enter held on the focused pad, the window lost, or the pad disabled or unmounted mid-press. Every start gets exactly one end. It does not time the read: the app does, and hands it back as progress, drawn as a tint rising with a scan line on its edge. Anything else you put on the pad (an ERROR verdict over the glyph) is laid out against the pad: position it absolute inset-0. Hold the pad below until the read completes.

Scanner terminal#

The other end of the reader: a terminal with its LEDs, a screen that changes with the state, and a divided header that stays green whatever the body says. Pick a state to see how each one paints.

Printer#

HandheldDevicePrinter puts a slot in the base of the shell and feeds its children out of it when printed: a slow 2.5s feed at a motor's pace (duration-feed), pulled back quicker when it turns false, and instant under reduced motion. Until then the paper is inside the device: clipped at the slot, inert and hidden from assistive tech, however long it is. To clear a receipt at once instead of pulling it back, stop rendering it.

The feed is a pure slot: it moves whatever you give it. HandheldDeviceReceipt is the thermal paper if you don't bring your own: a warm white strip (the cream theme's ground) in mono, torn along the bottom. The paper hangs below the shell, out of flow, so leave room under the device for it.

A physical object#

A gadget in your hand does not change color with the room, so the shell pins the dark theme (dark): its plastic, keys and legends read the same under light, cream, dark and moonlight. The materials are the dark theme's ground and ink mixed by the shell itself (the --handheld-* variables on its root, with a breath of --info for the cool cast of the plastic). The display glows in the four phosphor tokens, --phosphor, --phosphor-yellow, --phosphor-orange and --phosphor-red: light sources rather than text on a ground, so like --rating they are the same in every theme. They are also utilities (text-phosphor, bg-phosphor-red/10) for anything you lay over the glass yourself.

Display typeface#

The glass sets its text in font-lcd, which reads the --font-lcd variable and falls back to the mono stack. These docs load Share Tech Mono into it; load the face you want and point the variable at it:

import { Share_Tech_Mono } from "next/font/google"

const lcd = Share_Tech_Mono({ variable: "--font-lcd", weight: "400", subsets: ["latin"], preload: false })

// <html className={lcd.variable}>

Old engines#

The device is built to run in the embedded Chromium of a game or a desktop shell (103 and up): no container queries, no :has(), no subgrid, and no standalone translate, scale or rotate. The key press, the sensor's read and the paper feed all ride transform; every gradient is a plain linear-gradient() with no interpolation space; and every color mix is one color-mix() of two colors, which a build step targeting that engine can lower to rgb().

Accessibility#

Keys and the sensor are real buttons with a visible focus ring, and each is at least 44px tall. A key is named by its legend. The sensor is named by aria-label ("Hold to scan" by default) and reports the hold with aria-pressed. LEDs, the grille, the scanlines and the printer slot are decoration: say what a state means in words on the screen. The screen is not a live region, because a meter filling inside it would be read out on every step; put aria-live="polite" on the line whose change matters, like the verdict.

API reference#

FAQ#