info-flip-board

A responsive React split-flap information board with configurable messages, timing, colors, controlled and automatic modes, keyboard navigation, fullscreen support, and optional built-in sound.

Interactive board and timer demo · npm

Install

npm install info-flip-board

React and React DOM 18.2 or newer are peer dependencies. React 18 and React 19 are supported.

Usage

Import both the component and its published stylesheet:

import { FlipOffBoard } from 'info-flip-board';
import 'info-flip-board/styles.css';

const messages = [
  ['', 'ARRIVALS', 'ON TIME', 'PLATFORM 4', ''],
  ['', 'NEXT SERVICE', 'BOARDING NOW', 'HAVE A GOOD TRIP', ''],
];

export function InformationBoard() {
  return (
    <FlipOffBoard
      messages={messages}
      soundEnabled={false}
    />
  );
}

Countdown timer

FlipOffTimer renders an accurate split-flap countdown with Start, Pause, Resume, and Reset controls. Starting can request fullscreen because browsers only allow fullscreen from a user gesture.

import { FlipOffTimer } from 'info-flip-board';
import 'info-flip-board/styles.css';

export function PresentationTimer() {
  return (
    <FlipOffTimer
      durationSeconds={10 * 60}
      format="24"
      soundEnabled
      fullscreenOnStart
    />
  );
}

Timer durations must be whole seconds from 1 through 359999 (99:59:59). format="auto" displays MM:SS below one hour and HH:MM:SS otherwise. format="24" always displays HH:MM:SS.

Launch from npx

npx info-flip-board timer 10m --format 24
npx info-flip-board timer 1h30m --no-sound
npx info-flip-board --timer 90s --no-fullscreen

Durations use whole-number h, m, and s segments in descending order, such as 1h30m15s. The CLI binds an available port on 127.0.0.1, opens the default browser, and remains active until you press Ctrl+C.

| CLI option | Default | Description | | --- | --- | --- | | --format auto\|24 | auto | Select automatic or fixed HH:MM:SS display. | | --sound / --no-sound | sound on | Enable or disable the completion sound. | | --fullscreen / --no-fullscreen | fullscreen on | Control whether Start requests fullscreen. | | --no-open | browser opens | Print and serve the URL without launching a browser. |

Controlled mode

import { useState } from 'react';
import { FlipOffBoard } from 'info-flip-board';
import 'info-flip-board/styles.css';

export function ControlledBoard() {
  const [index, setIndex] = useState(0);

  return (
    <FlipOffBoard
      messages={messages}
      currentMessageIndex={index}
      onMessageChange={setIndex}
      autoPlay={false}
    />
  );
}

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | cols | number | 22 | Number of columns. | | rows | number | 5 | Number of rows. | | messages | string[][] | Built-in quotes | Messages represented as arrays of rows. | | messageInterval | number | 4000 | Visible duration before automatic rotation, in milliseconds. | | scrambleDuration | number | 800 | Character scramble duration, in milliseconds. | | flipDuration | number | 300 | Tile settle duration, in milliseconds. | | staggerDelay | number | 25 | Delay between tile transitions, in milliseconds. | | charset | string | Alphanumeric set | Characters used during scrambling. | | scrambleColors | string[] | Built-in palette | Tile colors used during scrambling. | | accentColors | string[] | Built-in palette | Corner accent colors. | | soundEnabled | boolean | true | Enables the bundled flap sound. | | volume | number | 0.8 | Audio volume from 0 to 1. | | autoPlay | boolean | true | Rotates messages automatically in uncontrolled mode. | | currentMessageIndex | number | undefined | Enables controlled mode. | | onMessageChange | (index: number) => void | undefined | Reports requested message changes. | | showKeyboardShortcuts | boolean | true | Enables keyboard controls and the shortcut hint. |

Timer props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | durationSeconds | number | Required | Initial countdown duration from 1 through 359999 seconds. | | format | 'auto' \| '24' | 'auto' | Automatic width or fixed HH:MM:SS. | | soundEnabled | boolean | true | Plays one completion sound when browser audio is available. | | fullscreenOnStart | boolean | true | Requests fullscreen from the Start interaction. | | volume | number | 0.8 | Completion audio volume from 0 to 1. | | onStateChange | (state) => void | undefined | Reports ready, running, paused, and completed states. | | onComplete | () => void | undefined | Runs once when the countdown reaches zero. |

Keyboard controls

When showKeyboardShortcuts is enabled:

• Enter, Space, or ArrowRight: next message
• ArrowLeft: previous message
• F: toggle fullscreen
• M: toggle sound
• Escape: close shortcuts or leave fullscreen

Keyboard events originating from inputs and textareas are ignored.

Browser and static rendering

The package does not access browser globals during module evaluation, so it can be imported by server-rendered and static-build React tooling. Audio, keyboard listeners, and fullscreen behavior initialize only in the browser.

Audio playback requires a user gesture under modern browser autoplay policies. In Astro, hydrate the component with a client directive. In Docusaurus or similar static-rendering systems, render or hydrate the interactive component on the client.

The timer CLI requires Node.js 20 or newer and opens a loopback-only HTTP server. If automatic browser launching is unavailable, the CLI prints the local URL for manual opening.

Development

npm install
npm run dev
npm run test
npm run lint
npm run build
npm run pack:check
npm run test:package

npm run validate runs linting, component tests, the library and site builds, package archive inspection, and packed-package tests against React 18 and React 19.

The library is written to dist/. The GitHub Pages site is written to site-dist/.

Publishing

1. Update package.json to the intended release version.
2. Run npm run validate.
3. Push the change and create a GitHub release tagged v<version>.
4. The release workflow verifies the tag, confirms the version is unpublished, rebuilds the package, and publishes the inspected archive with npm provenance.

The npm package must configure GitHub trusted publishing for:

• Repository: abudhahir/info-flip-board
• Workflow: .github/workflows/release.yml
• Environment: no npm environment is required by the workflow

If trusted publishing is unavailable, add a granular automation token as the NPM_TOKEN repository secret.

GitHub Pages setup

In the GitHub repository settings, set Pages → Build and deployment → Source to GitHub Actions. Pushes to main then build and deploy site-dist/ through .github/workflows/pages.yml.

License

MIT