ClockBoard

A 20×8 grid of analog clocks that animate together to form patterns and display the time. Canvas-rendered React component — 60fps, zero CSS imports.

Install

pnpm add clockboard

Peer dependency: react >=18.

Quick Start

import { ClockBoard } from 'clockboard'

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <ClockBoard />
    </div>
  )
}

The default behavior (clockRandom) cycles through randomized ambient patterns, displaying the current time whenever the minute changes.

The board fills its parent. The clock grid keeps a fixed 20×8 aspect ratio and scales uniformly to fit the padded area — constrained by whichever dimension is tighter.

Props

Behavior

| Prop | Type | Default | Description | |------|------|---------|-------------| | behavior | Behavior | clockRandom() | Dynamic behavior controlling pattern transitions over time | | pattern | GridPattern | — | Static pattern — sets all clocks to a fixed position (disables behavior) | | duration | number | 10000 | Transition duration in ms when using the pattern prop |

When pattern is set, it takes priority over behavior. The board animates to the given pattern once and holds. When pattern is cleared (set to undefined), the behavior resumes.

Appearance

| Prop | Type | Default | Description | |------|------|---------|-------------| | handColor | string | 'rgb(222, 222, 222)' | Color of the clock hands | | faceColor | string | '#141414' | Background color of each clock face | | boardColor | string | '#171717' | Background of the board container — any CSS background value, including gradients | | boardPadding | string | '4%' | Padding around the clock grid | | boardRadius | number | 8 | Border radius of the board in pixels | | clockGap | string | '0.5%' | Gap between individual clocks | | easing | 'ease-in-out' \| 'linear' | 'ease-in-out' | Easing curve for hand transitions | | rotation | 'clockwise' \| 'shortest' | 'clockwise' | Direction hands rotate — 'clockwise' always sweeps forward; 'shortest' takes the shortest arc | | className | string | — | CSS class on the outer container | | style | CSSProperties | — | Inline styles on the outer container |

// Full-viewport board
<ClockBoard style={{ height: '100vh' }} />

// Fixed-size container
<div style={{ width: 800, height: 400 }}>
  <ClockBoard />
</div>

Behaviors

Behaviors control what the board displays over time. They receive an apply callback to push patterns and return a cleanup function.

type Behavior = (apply: ApplyPattern) => () => void
type ApplyPattern = (pattern: GridPattern, duration?: number) => void

Built-in Behaviors

clockRandom

The default. Cycles through random ambient patterns and displays the current system time (24-hour format) whenever the minute changes.

import { ClockBoard, clockRandom } from 'clockboard'

<ClockBoard />
// equivalent to:
<ClockBoard behavior={clockRandom()} />

// Custom options
<ClockBoard behavior={clockRandom({ duration: 3000, hold: 2000, timeDuration: 4000, timeHold: 15000 })} />

Accepts an options object or positional args (patterns?, duration?, hold?, timeDuration?, timeHold?).

| Field | Type | Default | Description | |-------|------|---------|-------------| | patterns | GridPattern[] | ALL_PATTERNS | Pool of ambient patterns | | duration | number | 10000 | Ambient transition duration (ms) | | hold | number | 800 | Pause between ambient transitions (ms) | | timeDuration | number | 5000 | Time display transition duration (ms) | | timeHold | number | 10000 | How long the time stays visible before resuming ambient (ms) |

clockCycle

Same as clockRandom but steps through ambient patterns in order rather than randomly. Same signatures and defaults.

import { ClockBoard, clockCycle } from 'clockboard'

<ClockBoard behavior={clockCycle()} />
<ClockBoard behavior={clockCycle({ hold: 250 })} />

clock

Pure time display. Shows the current system time and updates every minute. No ambient patterns.

import { ClockBoard, clock } from 'clockboard'

<ClockBoard behavior={clock()} />
<ClockBoard behavior={clock({ duration: 2000 })} />

| Field | Type | Default | Description | |-------|------|---------|-------------| | duration | number | 10000 | Transition duration when the time updates (ms) |

random

Continuously transitions through random ambient patterns. No time display.

import { ClockBoard, random } from 'clockboard'

<ClockBoard behavior={random()} />
<ClockBoard behavior={random({ hold: 250 })} />

Accepts an options object or positional args (patterns?, duration?, hold?).

| Field | Type | Default | Description | |-------|------|---------|-------------| | patterns | GridPattern[] | ALL_PATTERNS | Pool of patterns | | duration | number | 10000 | Transition duration (ms) | | hold | number | 800 | Pause after transition before next (ms) |

cycle

Cycles through ambient patterns in order. No time display. Same signatures and defaults as random.

import { ClockBoard, cycle } from 'clockboard'

<ClockBoard behavior={cycle()} />
<ClockBoard behavior={cycle({ duration: 3000 })} />

Custom Behaviors

import { ClockBoard, NOON, RADIAL } from 'clockboard'
import type { Behavior } from 'clockboard'

const alternate: Behavior = (apply) => {
  let flip = false
  const interval = setInterval(() => {
    apply(flip ? NOON : RADIAL, 3000)
    flip = !flip
  }, 8000)
  apply(NOON, 3000)
  return () => clearInterval(interval)
}

<ClockBoard behavior={alternate} />

The apply function accepts any GridPattern and an optional duration in milliseconds.

Patterns

A GridPattern is an 8-row × 20-column 2D array where each cell is a ClockState — a tuple of two angles in degrees ([hand1, hand2]). 0° is 12 o'clock, 90° is 3 o'clock, 180° is 6 o'clock, 270° is 9 o'clock.

Built-in Ambient Patterns

All 13 patterns are individually exported and also available as the ALL_PATTERNS array:

import {
  NOON, RADIAL, CONVERGE, CHECKERBOARD, WAVE, VORTEX,
  RINGS, CONCENTRIC_RECTS, CROSS_STITCH,
  BLOOM, CHEVRONS, SPIRAL_ARMS, WINDMILL,
  ALL_PATTERNS,
  randomPattern, // generates a unique random pattern each call
} from 'clockboard'

| Pattern | Description | |---------|-------------| | NOON | All hands at 12 o'clock — clean reset | | RADIAL | Hands radiate outward from grid center — starburst | | CONVERGE | All hands point inward toward center — vortex sink | | CHECKERBOARD | Alternating vertical and horizontal bars | | WAVE | Sine wave undulating across columns | | VORTEX | Radial direction twisted by distance — galaxy spiral | | RINGS | Angle grows with distance from center — concentric rings | | CONCENTRIC_RECTS | Rectangular borders from edge to center | | CROSS_STITCH | Alternating X and + shapes — woven texture | | BLOOM | Hands splay wider with distance — flower opening | | CHEVRONS | Rows of V-shapes alternating direction | | SPIRAL_ARMS | Twisted V-shapes following a spiral curve | | WINDMILL | 2×2 repeating windmill — each cell rotated 90° from neighbors |

Using the pattern Prop

import { useState } from 'react'
import { ClockBoard, RADIAL, VORTEX, NOON } from 'clockboard'

function App() {
  const [pattern, setPattern] = useState(RADIAL)

  return (
    <>
      <ClockBoard pattern={pattern} duration={3000} />
      <button onClick={() => setPattern(RADIAL)}>Radial</button>
      <button onClick={() => setPattern(VORTEX)}>Vortex</button>
      <button onClick={() => setPattern(NOON)}>Reset</button>
    </>
  )
}

Time Composition

import { ClockBoard, composeTime } from 'clockboard'

// Static display of 14:30
<ClockBoard pattern={composeTime(14, 30)} />

composeTime(hours, minutes) returns a full GridPattern with the time rendered in the center 18×6 region.

Custom Patterns

import type { GridPattern, ClockState } from 'clockboard'

const myPattern: GridPattern = Array.from({ length: 8 }, (_, row) =>
  Array.from({ length: 20 }, (_, col): ClockState => {
    const angle = (row * 20 + col) * (360 / 160)
    return [angle, angle + 180]
  })
)

<ClockBoard pattern={myPattern} />

Grid Dimensions

The board is a fixed 20 columns × 8 rows (160 clocks).

Time layout within the grid:

• The outermost ring of clocks (border) stays in idle position (both hands at 225°)
• The inner 18×6 region displays content
• Each digit occupies a 4×6 block
• The colon between hours and minutes is a 2×4 block
• Layout: [border] [digit] [digit] [colon] [digit] [digit] [border]

Multiple Instances

Each ClockBoard is fully independent:

<ClockBoard behavior={clock()} boardColor="#1a1a2e" handColor="#e94560" />
<ClockBoard behavior={random()} boardColor="#0f3460" handColor="#16213e" />
<ClockBoard pattern={RADIAL} boardColor="#222" faceColor="#333" />

Types

import type {
  ClockState,      // [hand1: number, hand2: number]
  GridPattern,     // ClockState[][] (8 rows × 20 cols)
  ApplyPattern,    // (pattern: GridPattern, duration?: number) => void
  Behavior,        // (apply: ApplyPattern) => () => void
  ClockBoardProps,
} from 'clockboard'

Full-Screen Display

<!DOCTYPE html>
<html>
<head><style>body { margin: 0; background: #171717; }</style></head>
<body>
  <div id="root"></div>
  <script type="module">
    import { createRoot } from 'react-dom/client'
    import { ClockBoard } from 'clockboard'
    createRoot(document.getElementById('root')).render(
      <ClockBoard style={{ height: '100vh' }} />
    )
  </script>
</body>
</html>

Set the body background to match boardColor so the display is seamless edge to edge.

Changelog

0.1.0

• Overhauled animation engine for reliable, uninterrupted transitions
• Fixed animation timing when tab loses focus or window is backgrounded
• Added gradient support for boardColor
• Fixed resizing issues

0.0.1

• Initial release

License

MIT